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First Edition (Nay 1986) 

This edition applies to the Event Driven Executive Indexed 
Access Methods Version 2, Modification Level 1 (Program Number 
5719-AM4) until otherwise indicated by neui editions or technical 
neNsletters. Technical changes to the text for Version 2.1 are 
indicated by vertical lines to the left of the changes. 

Use this publication only for the purpose stated in the Preface. 

Changes are periodically made to the information herein; any 
such changes Mill be reported in subsequent revisions or Techni- 
cal NeMsletters. 

It is possible that this material may contain reference to> or 
information about» IBM products (machines and programs) » pro- 
gramming* or services that are not announced in your country. 
Such references or information must not be construed to mean 
that IBM intends to announce such IBM products^ programming^ or 
services in your country. 

Publications are not stocked at the address beloM. Requests for 
copies of IBM publications should be made to your IBM represen- 
tative or the IBM branch office serving your locality. 

This publication could contain technical inaccuracies or 
typographical errors. A form for reader comments is provided at 
the back of this publication. If the form has been removed^ 
address your comments to IBM Corporation^ Information Develop- 
ment, Department 28B (3405) , P. 0. Box 1328, Boca Raton, 
Florida 33429-1328. IBM may use or distribute any of the infor- 
mation you supply in any May it believes appropriate Nithout 
incurring any obligation Mhatever. You may, of course, continue 
to use the information you supply. 

(c) Copyright International Business Machines Corporation 1986 
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gMyiHARY OF PHANGES FPR YgR^lQN ZrX 

This document reflects the folloMing changes. 

— Record Level Block I/O and High Speed Block Reads - 

On data block reads» you can instruct $IAN to bypass its own 
buffer and read data into a buffer you specify in your applica- 
tion program. Changes to the text for this addition appear 
throughout the document. 

— Allocation of an indexed file Mith an application program - 

You can noM allocate and format a primary or secondary indexed 

file from an application program using the neu load module* 

$IAMUT3. Changes to the text for this addition appear in a new 
Chapter 6 . 

A vertical line in the left margin indicates neM or changed material. 
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PREFACE 



The material in this section is a guide to using this book. It defines 
the purpose, audience, and content of the book as well as listing back- 
ground materials and aids for using thg book. 



PURPOSE 



This publication describes houi to use the Indexed Access Method Version 
2. If hoN to set up indexed files and hou to develop application programs 
using indexed files. 



AUDIENCE 



This manual is intended for use by^ 

• Application designers who design applications that use the Indexed 
Access Method Version 2.1. 

• Application programmers who develop applications that use the 
Indexed Access Method Version 2.1. 

Applications for the Series/l can be developed in several languages. 
Unless otherwise noted in this section, material in this book is 
intended for use in the development of applications in any of the fol- 
lowing languages: COBOL, the Event Driven Language (EDL), and PL/1. 



HOH THIS BOOK IS ORGANIZED 



This book describes the Indexed Access Method in the following order: 

Chapter 1, "Introduction" provides an overview of the Indexed 
Access Method. 

Chapter 2, "Using the Indexed Access Method," provides a brief 
description of what indexed files are, how to set up an indexed 
file, and application program request statements. 

Chapter 3, "Defining Primary Index Files," describes the format of 
the primary index file and how to use the $IAMUT1 utility to set up 
your indexed files. 

Chapter 4, "Loading the Primary Index File," describes loading data 
records into a primary index file using an application program. 

Chapter 5, "Building a Secondary Index," provides information on 
using secondary keys, what a secondary index is and does, and how to 
set up and load a secondary index. 

Chapter 6, "Allocating Indexed Files from an Application Program," 
describes how to use $IAMUT3 to allocate and format primary and sec- 
ondary indexed files from an application program. 

Chapter 7, "Processing the Indexed File," describes how to process 
the indexed file with an application program. 

Chapter 8, "Coding The Indexed Access Method Requests," provides 
information needed to code EDL applications which use the Indexed 
Access Method. This chapter is intended only for EDL application 
developers. 
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Chapter 9* **The $IAMUT1 Utility*** provides information needed to use 
$IAMUT1> including the completion codes it generates. 

Chapter 10 » **The $VERIFY Utility*** provides information needed to \ m 

use $VERIFY. ^"^ 

Chapter 11» **Storage and Performance Considerations** describes the 
storage and performance characteristics of the Indexed Access Method 
and hoM to tailor the Indexed Access Method to the processing 
requirements of your installation. 

Chapter 12» **Error Recovery** describes some of the error recovery 
procedures available for use with Indexed Access Method 
applications. 

Chapter 13* **Installing the Indexed Access Method*** provides an 
overview of the installation process. 

Appendix A* **Summary of Calculations*** provides a summary of calcu- 
lations for calculating the various blocks which make up indexed 
f i les. 

Appendix B* **Preparing Indexed Access Method Programs*** provides an 
overview of preparing an Indexed Access Method application and a 
sample $JOBUTIL procedure for an EDL application. 

Appendix C* **Coding Examples*** provides comprehensive examples of 
Indexed Access Method programs. This appendix is for application 
developers using EDL* COBOL* or PL/I as their application program- 
ming language. 



AIDS IN USIKG THIS PUBLICATION 

Illustrations in this book are enclosed in boxes. Many illustrations '\^' 

display screens generated while using the Event Driven Executive system. 
In those cases where the actual data exceeds the size of the box* the 
information may be illustrated in a modified format. 

In display screens appearing in this manual* operator input is shown in 
bold type. This highlighting is for illustrative purposes only* to dis- 
tinguish data entered by the operator from that generated by the system. 



CONTACTING IBM ABOUT PROBLEMS 

You can inform IBM of any inaccuracies or problems you find when using 
this book by completing and mailing the Reader *s Comment Form provided 
in the back of the book. 

If you have a problem with the IBM Series/1 Event Driven Executive ser- 
vices* refer to the IBM Series/1 Software Service Guide* GC34-0099. 
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CHAPTER 1. INTRODUCTION 



The Indexed Access Method licensed program is a data management facility 
that executes on an IBM Series/1 processor under the Event Driven Execu- 
tive Supervisor and Emulatorf Version 5 or later. The Indexed Access 
Method provides keyed access to each of your individual data records. 



WHAT THE INDEXED ACCESS METHOD DOES 

This licensed program builds* maintains* and accesses a data structure 
called an indexed file . 

Your data records can be loaded by the Indexed Access Method utility* 
$IAMUT1* or they can be loaded using an application program. Data 
records can then be added* deleted* modified* or accessed quickly and 
efficiently for processing by your application program. Uhen reorgan- 
ization of eir\ indexed file is required the utility can be used to unload 
and reorganize the file. 

When this licensed program is used* each of your records is identified 
by the contents of a predefined field called a key . The Indexed Access 
Method builds and maintains an index for those keys and through this 
index fast access to each record is provided. Your data records can be 
accessed either by key* or sequentially in ascending key sequence* using 
Indexed Access Method requests. 



INDEXED ACCESS METHOD FEATURES 

The Indexed Access Method offers the follouiing features: 

• Record access by a primary key or secondary keys - You can access 
records in an indexed file by one or more keys. Secondary keys use 
a separate index and Indexed Access Method provides the connection 
between the primary index files and secondary indexes. Duplication 
of secondary key fields is permitted. 

• Support for high insert and delete activity - Free space can be dis- 
tributed throughout the file and in a free-pool at the end of the 
file so that new records can be inserted. The space occupied by a 
deleted record is immediately available for inserting a neui record. 

• Direct and sequential access - You can access records either random- 
ly by key* or sequentially in ascending key sequence. 

• Data paging - You can improve Indexed Access Method performance by 
using data paging. Uith this feature active* the Indexed Access 
Method retains recently-used blocks of data records resident in main 
storage. 

• Dynamic file structure - A dynamic file structure adjusts itself as 
needed to handle record additions and deletions. This provides a 
quick and easy method of designing an indexed file. 

• Concurrent access to a single file by several requests - These 
requests can be from one or more programs. Data integrity is main- 
tained by a file-* block-* and record-level locking system that pre- 
vents other programs from accessing the portion of the file being 
modified. 

• Implementation as a separate task - A single copy of the Indexed 
Access Method executes and coordinates all requests. A buffer pool 
supports all requests and optimizes the space required for physical 
I/O; the only buffer required in an application program is the one 
for the record being processed. 
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Block I/O - On data block reads^ you can instruct $IAM to bypass its 
own buffer and read data into a buffer you specify in your applica- 
tion program. This allows you to process blocks of data in an 
application program instead of individual data records, and thus 
reduce the number of accesses to $IAM. Applications that use block 
I/O support can be coded in Event Driven Executive language or 
Series/1 Assembler language. 

Input records - Either blocked or unblocked input records are 
accepted. 

$IAMUT1 - A utility program that allows you to maintain a secondary 
index directory, create, format, load, unload, and reorganize an 
indexed file. The load and unload functions accept either blocked 
or unblocked records. 

$IAMUT3 - A load module that allows you to allocate and format a 
primary or secondary indexed file from an application program. 

$VERIFY - A utility program that allows you to check the integrity 
of the index structure, print control blocks, and print a free space 
report for an indexed file. 

Error logging - If multiple error return codes occur, errors are 
logged in the system error log. 

$ILOG - The error log entries can be printed by using the $ILOG 
ut i 1 i ty. 

File compatibility - Files created by the Event Driven Executive 
Indexed Access Method are compatible with those created by the IBM 
Series/1 Realtime Programming System Indexed Access Method licensed 
program, 5719-AMl and 5719-AM2 provided that the block size is a 
multiple of 256. 

Data protection - All input/output operations are performed by sys- 
tem functions. Therefore, all data protection facilities offered by 
the system also apply to indexed files. The following additional 
data protection is provided* 

— The exclusive option specifies that the file is for the exclu- 
sive use of a requester. 

— File-level, block-level, and record-level locking automatically 
prevents two requests from accessing the same file, the same 
block, or the same data record simultaneously. 

— The immediate write back option causes all file modifications 
(delete, insert, update) to be written back to the file imme- 
diately. 

— Accidental key modification for primary keys is prevented to 
help ensure that your index matches the corresponding data. 

Distribution packaging - The Indexed Access Method is distributed 
with the following variations available- 

— A full function package that is intended to be totally resident. 

— A full function package which uses an overlay structure. 

— A totally resident package without data paging. 

— A package without data paging which uses an overlay structure. 
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LANGUAGES COMPATIBLE WITH INDEXED ACCESS METHOD 

The follouiing programming languages can be used to code Indexed Access 
Method programs: 

• COBOL 

• EDL 

• PL/I. 

In addition^ the Transaction Processing System* which is an application 
development tool* can be used to code Indexed Access Method programs. 

Note: Block mode support is not available for applications using COBOL* 
PL/1» and the Transaction Processing System. 






COMPONENTS OF INDEXED ACCESS METHOD 

The Indexed Access Method consists of the following components' 

• Four load modules from which you can select to support your applica- 
tion program Indexed Access Method requests. These load modules are 
named' 

— $IAM (full function with overlay) 

— $IAMRS (full function resident) 

— $IAMNP (overlay without data paging) 

— $IAMRSNP (resident without data paging). 

The module you select will be named $IAM after installation. 

• A load module* $IAMST6M* which is used to obtain the data paging 
area* if the data paging feature is requested. 

• A set of object modules that you may use to generate a customized 
load module. If you use one of the four supplied load modules* you 
do not need the object modules. 

• Two object modules* lAM and lAMFR* that are link modules . You 
include lAM with your application program* using the linkage editor* 
to provide the interface to the Indexed Access Method. If you are 
going to take advantage of the block I/O features of the Indexed 
Access Method, you also include lAMFR. Related performance consid- 
erations are covered under "Other Performance Considerations" on 
page 11-6 in chapter 11. 

• Three copy code modules for inclusion in EDL programs* lAMEQU, 
FCBEQU* and IDEFEQU. lAMEQU provides symbolic parameter values for 
constructing CALL parameter lists. FCBEQU provides a map of the 
file control block. IDEFEQU provides a map of the parameter list 
required for $IAMUT3. 

• Load modules for each of the Indexed Access Method utilities 
$IAMUT1* $IAMUT3, $VERIFY* and $ILOG. 
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CHAPTER 2. USING THE INDEXED ACCESS METHOD 



The purpose of this chapter is to familiarize you with some fundamentals 
of the Indexed Access Method. Some of the features mentioned in the 
previous chapter Mill be described only in part here so that a basic 
example can be constructed. The purpose of this example is to demon- 
strate the ease with which you can establish an indexed file and to help 
you select which parts of the book apply directly to your application 
requi rements. 



YOUR DATA RECORD 



c 



The data records you wish to process with the Indexed Access Method have 
the following specific requirements: 

• The records must contain a common field that can be used as a prima- 
ry key 

• Each record must have a unique primary key 

• The initial records to be loaded must be in ascending order by the 
primary key 

• All records that make up an indexed file must be of the same length. 

The primary key is any field you designate within your data records. 
The key field must begin at the same location in each record. Each key 
field must have the same length. The key in each record must be unique 
within the file (data set). 

The data records that you will initially load must be in ascending 
order r based upon the field you use as the key. If your data records 
are not ready to be loaded when you define your primary indexed file« 
the records can be loaded later by an application program or with the LO 
(load) command of $IAMUT1. 

Your application might use an employee number as the primary key in an 
indexed file for some applications. You might want to define secondary 
keys» such as employee name» for the same file for other applications. 
Using secondary keys requires a secondary index to be defined. Defining 
a secondary index and using secondary keys is described in Chapter 
5, "Building a Secondary Index." 

Mhether you use the $IAMUT1 utility to load your data records into an 
indexed file from a sequential file* or load them with an application 
program* you must know the format of your input data record. 

Following is a sample record layout. Although the primary key is shown 
starting in position 1* it could have been anywhere in the record. 



Empl . 
Number 



Employee 
Name 



-> <- 



6--Byte 

Primary 

Key 



2^--Byte 

Secondary 

Key 



80 byte data record 



Address 



-> <- 



Zip 
Code 



'//' 
-//' 



-//' 



> < > <-// 

2^-Byte 5-Byte 21-Byte 
Address Data 

Field 
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he records used for our example have the following attributes: 
Block size 256 bytes 
Record size 80 bytes 
Primary key length 6 bytes 
Key position 1. 



SETTING UP AN INDEXED FILE USING JIAMUTl 

Use the Indexed Access Method utility program, $IAMUT1> to set up an 
indexed file. After this utility is loaded into the system for exe- 
cution, the utility displays a sequence of prompts. The prompts are 
questions displayed on a terminal one at a time to which you can reply 
using the terminal keyboard. Responding to the questions causes the 
utility to perform the required steps to? 

1. Set up the structure of the file (space for records to be loaded, 
free space for inserts, and an index). 

2. Allocate a data set (the utility prompts you for a data set and vol- 
ume name and calls $DISKUT3 to allocate space for the indexed file), 

3. Define and format the indexed file. 

4. Load the data records into the indexed file. 

Loading and using the SE (set parameter) command of the $IAriUTl utility 
is described here for the purpose of our example, however, for a com- 
plete description of ^lAMUTl see Chapter 9, "The $IAriUTl Utility." 

The responses for our example are shown in bold face type inside the 
box. The bold bracketed numbers at the left, outside the box, identify 
explanatory remarks that we have written below the box using the same 
bracketed numbers. Of course these brackets and explanations do not 
appear on the screen when $IAMUT1 is being used. 

The $IAMUT1 Indexed Access Method utility can be loaded with the Event 
Driven Executive operator command $L $IANUT1. 

Ulhen $IAMUT1 is loaded the first prompt is displayed as follows? 






[1] 



ENTER COMMAND (?): SE 



[1] Entering the letters SE (set parameters), followed by pressing the 
ENTER key, causes four options to be displayed? 



[2] 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 ~ ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATASET 
ENTER OPTION: 1 
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[2] The response digit *1*» causes prompts to folloM Mhich alloMS you to 
define an indexed file with a minimum of information. This response 
causes a one line prompt to be displayed. 

Note: Although the following prompts are displayed one line at a time 
when using the utility, the prompts and responses are listed here in 
logical groups for simplicity in describing them. 



[3] 


SECONDARY INDEX (Y/N):? N 




DEFAULT NEW VALUE 


[4] 


RECORD SIZE 




0:80 


[5] 


KEY SIZE 




0:6 


[61 


KEY POSITION 




1:1 


t71 


BLOCKING FACTOR (RECORDS PER BLOCK) 




1:3 


[8] 


NUMBER OF BASE RECORDS 




0:5 


[9] 


ESTIMATED TOTAL RECORDS 




6:20 


[101 


TYPE OF INSERT ACTIVITY(C=CLUSTERED,R= 


=RANDOM) 


C:R 


[11] 


DATA SET SIZE IN EDX RECORDS: 


15 




[12] 


INDEXED ACCESS METHOD RETURN CODE: 


-1 




[13] 


SYSTEM RETURN CODE: 


-1 




[14] 


CREATE/DEFINE FILE (Y/N)?: Y 







J#<»V 
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[3] The first prompt, "SECONDARY INDEX (Y/N)?:" asks if you are specify- 
ing a secondary index. The response was N for no, because we are defin- 
ing the parameters for a primary indexed file. 

[4] The second prompt, "RECORD SIZE" requests the length that the 
records are to be in the indexed file which you are defining. 

Note that there are two columns near the right-hand edge of the display. 
The column on the left is headed by the word "DEFAULT". In the default 
column the values are listed that will be used in setting up the file if 
no value is supplied in the response (only the ENTER key is pressed). 
The column on the right, headed "NEW VALUE" is where the decimal value 
is placed from your keyboard response, followed by pressing the ENTER 
key. 

In this example we are using a record length of 80. 

[5] The "KEY SIZE" prompt is for the length of the primary key in the 
data record. In this example we are using a key which is 6 bytes long. 

[6] Our key field begins in position 1 of the data record. 

[71 We are requesting that our indexed file be blocked with 3 records in 
each 256-byte block. 

[8] The number of base record slots to be defined is 5. This number is 
based on the number of data records we plan to load. You cannot load 
more records than this value, however, it does not restrict you from 
inserting new data records in the frea (empty) slots later. 

[9] The total number of records that we anticipate that this resultant 
indexed file will ever contain is 20. 

[10] The type of record insert activity is to be R (random). The 
records added to this file will be inserted by an application program 
when those records are available. 

The choice of random or clustered is based on the type of record addi- 
tions that are anticipated. Random is chosen when the records to be 
added are expected to be evenly distributed throughout the file. 

Clustered is chosen when the records to be added are expected to be in 
groups, relative to their range in key value. 
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[11] FolloMing the previous response the system Mill display the number 
of records required to contain an indexed file using the parameters you 
have supplied. 

E12] The Indexed Access Method return code (-1) indicates that the 
parameters you supplied are acceptable; no Indexed Access Method rules 
have been violated. 

[133 The system return code (-1) should always be -1 if the Indexed 
Access Method return code is -1. If any errors are encountered^ the 
return code may provide additional information. 

[14] If you have verified that the parameters you entered are correct* 
the data set (file) size in EDX records is acceptable* and the return 
codes are both -1> you can reply Y and the file will be defined and cre- 
ated. 

If you wish to change any of the parameter values that you previously 
supplied* respond N to this prompt and you will be prompted for the next 
command. To re-enter your responses* reply SE and the prompt sequence 
will be repeated. 

A Y in response to this prompt causes the next prompt sequence to begin. 



[15] 
[16] 

[17] 
[18] 



[19] 



ENTER DATA SET (NAME* VOLUME) : IAMFILE,EDX003 

DYNAMIC DATA SET EXTENTS ON FILE (Y/N) N 

NEW DATA SET IS ALLOCATED 

DO YOU WANT IMMEDIATE WRITE-BACK? Y . 

INVOKE LOAD(L), REORGANIZE(R) OR END(E) 

DEFINE IN PROGRESS 

DATA SET SIZE IN EDX RECORDS: 

INDEXED ACCESS METHOD RETURN CODE: 

SYSTEM RETURN CODE: 

PROCEED WITH LOAD/REORGANIZE (Y/N) ?Y 

LOAD ACTIVE 



AFTER CURRENT FUNCTION L 



15 
-1 
-1 



[15] The data set and volume name you reply to this prompt is what 
$DISKUT3 uses to allocate a data set for your file. A successful allo- 
cation results in the information message "NEW DATA SET IS ALLOCATED". 

[16] If you do not want the file allocated with data set extents* reply 
*N* to this prompt. This feature is supported with EDX Version 5.1 and 
subsequent releases. 

[17] The immediate write back option is recommended for most applica- 
tions. It means that we want any record in the indexed file that we 
process with our application program to be written back to the indexed 
file immediately. Otherwise* the record will be held in a buffer until 
that buffer is needed by the Indexed Access Method. 

[18] The action to be taken after the file is defined. 

• Load base records (as shown in this example) 

• Reorganize an existing indexed file for loading into the file being 
def i ned 

• End the current SE command session. 

[19] Because of the L response to the previous prompt* this prompt is to 
verify the action to be taken. 

We are going to load records during this session so the response is Y. 
Following the 'LOAD ACTIVE* information message* the prompts continue. 
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[20] 
[21] 
[22] 
[23] 
[24] 

[25] 
[26] 



$FSEDIT FILE RECSIZE = 128 

INPUT RECORD ASSUMED TO BE 80 BYTES. OK?: N 

ENTER RECORD SIZE: 128 

ENTER INPUT BLOCKSIZE (NULL = UNBLOCKED): 256 

ENTER INPUT DATA SET (NAME» VOLUME) : SEQ01>EDX003 

INPUT REC GT OUTPUT REC. TRUNCATION WILL OCCUR 

OK TO PROCEED:? Y 

LOAD IN PROCESS 

END OF INPUT DATA SET 

ANY MORE DATA TO BE LOADED?: N 

5 RECORDS LOADED 

LOAD SUCCESSFUL 



The next sequence of prompts refers to the input data set containing the 
data records that are going to be loaded into the indexed file. 

[20] The utility accepts input records Mhich have been prepared by the 
Event Driven Executive utility $FSEDIT. The $FSEDIT record size is 128. 

[21] Because the output data set (indexed file) records are 80 bytes* 
this prompt determines Mhether the input sequential data set is also an 
SO byte record data set. 

If you use the Event Driven Executive edit utilities to prepare your 
data records for input to the Indexed Access Method* remember that these 
utilities place one 80-byte line from $FSEDIT in a 128-byte record. The 
first record begins at location 1, and the second record begins at 
location 129. Two of these 128-byte records make one 256-byte EDX 
record. 

Because Me used $FSEDIT* Me responded N. 

[22] This prompt requests the input data record attributes. 

Because our input data records Mere created by $FSEDIT» our 80-*byte 
records Mere converted to 128-byte records. Therefore* our response is 
128. 

[23] The Indexed Access Method utility* $IAMUT1 accepts your records as 
either unblocked (one record per block) or blocked (more than one record 
per block) input. The utility prompts you for the block size of the 
input data set being loaded. If the input data set is unblocked* reply 
to the block size prompt by pressing the Enter Key. See "Blocked and 
Unblocked Sequential Data Sets" on page 9-23 for a description of 
blocked and unblocked sequential data sets. 

If your input data records are unblocked sequential* reply by pressing 
the Enter Key. If your input is blocked sequential* reply Mith the 
actual blocksize that Mas used to prepare your input data records. 

Our example uses blocked sequential records* created on every line by 
$FSEDIT, Mith a blocksize of 256. 

[24] Reply to this prompt Mith your input data record data set and vol- 
ume name. Our response Mas SEQ01»EDX003. 

[25] This prompt verifies Mhether truncation of the input records is 
acceptable. Because our record size specified is actually 80 bytes 
long* but Me responded 128 because $FSEDIT converts the records to 128 
bytes* the folloMing Marning message is displayed. "INPUT REC GT OUTPUT 
REC. TRUNCATION WILL OCCUR" This means that the extra bytes attached by 
$FSEDIT to our 80-byte data records will now be removed. The response 
is Y. 

The information message "LOAD IN PROCESS" tells us that $IAMUT1 is read- 
ing the input data set and loading the input data records into the base 
record slots. The information message "END OF INPUT DATA SET" indicates 
that the end-of-file condition* on the input data set* has been encount- 
ered. 
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[26] This prompt alloMs you to specify another input data set» if more 
data records are to be loaded from another data set. In this example* 
only 1 data set is being used and the response of N caused the records 
loaded statistics to be displayed* followed by the "LOAD SUCCESSFUL" 
message. 

The design of an indexed file varies according to your application. A 
comprehensive approach to designing your indexed files begins Mith "De- 
fining The File Structure With $IAMUT1" on page 3-4. 



o 



PROCESSING THE INDEXED FILE 

Now that the indexed file has been defined* formatted, and loaded with 
data records, the file is ready for an application program to access any 
of the records in the indexed file for processing. An application pro- 
gram might use the following EDL coded requests to open the indexed file 
and retrieve a record. 





X 

X 
X 


OPEN 


THE INDEXED FILE FOR PROCESSING 


[1] 


X 
X 
X 




CALL lAM, (PROCESS), lACB, (DSD, (OPENTAB), (SHARE) 




PERFORM A DIRECT RETRIEVAL OF THE RECORD WHOSE KEY IS JONES PW 


C2] 




CALL IAM,(GET),IACB, (BUFF), (KEYl) 




KEYl 
OPENTAB 

lACB 


TEXT 
DATA 
DATA 
DATA 
DATA 


•JONES PW' 

p.Qf 

A(IAMERR) 

F»0' 

F'0» 



k^ 



[1] This Indexed Access Method request opens the primary index file in 
process mode so that other requests can be issued for processing records 
in the indexed file. 

121 This Indexed Access Method request retrieves a record from the 
indexed file. The primary key of this record contains the name 'JONES 
PW'. 



2-6 SC34-0771 






o 



Functions of the Requests 

FolloNing is a list of functions that you can perform using the Indexed 
Access Method requests in your application program: 

Initiate general purpose access to an indexed file uiith a PROCESS 
request. After the PROCESS request has been issued* any of the follow- 
ing functions can be requested: 

• Direct reading - Retrieving a single record independently of any 
previous request. 

• Direct updating - Retrieving a single record for update; complete 
the update by either replacing or deleting the record. 

• Sequential reading - Retrieving the next logical record relative to 
the previous sequential request. 

The first sequential request can access the first record in the file 
or any other record in the file. 

• Sequential updating - Retrieving the next logical record for update; 
complete the update by either replacing or deleting the record. 

• Inserting - Placing a single record* in its logical key sequence* 
into the indexed file. 

• Deleting - Removing a single record from the indexed file. 

• Extracting - Extracting data that describes the file. 

Note that the update functions require more than one request. 

Ulhen a function is complete* another function may be requested* except 
that a sequential processing function can be follouied only by another 
sequential function. You can terminate sequential processing at any 
time by issuing a DISCONN or ENDSEQ request. An end-of-data condition 
also terminates sequential processing. 

A complete list of the Indexed Access Method requests* the operand 
descriptions, and correct syntax is described in Chapter 8* "Coding the 
Indexed Access Method Requests" on page 8-1. There are also coding 
examples using the Indexed Access Method requests in three programming 
languages in Appendix C, "Coding Examples." The languages used in the 
examples are Event Driven Language* COBOL* and PL/I. The purpose of 
these examples is not to shoM any particular application* but to help 
you when planning and writing your application program. 
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SUNNARY 



This chapter has introduced some fundamentals of using the Indexed 
Access Method. The references in this chapter to other chapters in this 
manual Mere placed there to help you select the specific information you 
need for your application. A list of those references is repeated here 
to assist you in locating the detailed information on the listed sub- 
jects. 

• For a complete description of $IAI1UT1 see Chapter 9» "The $IAMUT1 
Utility" 

• A comprehensive approach to designing your indexed files is 
described in Chapter 3» "Defining Primary Index Files" 

• Defining a secondary index for using secondary keys is described in 
Chapter 5, "Building a Secondary Index" 

• Description of blocked and unblocked sequential data sets is 
described in "Blocked and Unblocked Sequential Data Sets" on page 
9-23 

• The complete list of Indexed Access Method request 5» the operand 
descri pti onSf and correct syntax is described in Chapter 8» "Coding 
the Indexed Access Method Requests" 

• Guide line information on processing the indexed file is located in 
Chapter 8^ "Coding the Indexed Access Method Requests." This guide- 
line information should be read prior to planning and coding your 
application program. 



f 
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CHAPTER 3. DEFINING PRIMARY INDEX FILES 

This chapter presents the following major topics^ 

• Primary Indexed Files 

• Designing Indexed Files Using $IAMUT1 - option 1 

• Designing Indexed Files Using OIAMUTl - option 2 

— Indexed Access Method Blocks 

— Index Blocks 

— File Control Block 

— File Structure Types 

— Option 2 Examples 

• Designing Indexed Files Using $IAMUT1 - option 3 

• Defining/Creating, and Loading A File - Summary. 

This chapter provides information for defining indexed files and is 
arranged according to your option selection when using $IAMUT1. The 
beginning of the chapter has information which applies to any type of 
primary index file design. That general information section is followed 
immediately with an example using $IAMUT1, option 1. The option 2 sec- 
tion is next and contains information that you will need to know prior 
to designing an index file with $IAMUT1, option 2. The fourth section 
applies to using $IAMUT1, option 3. 



^k*>^ 



PRIMARY INDEX FILES 



A primary index file contains data records, a multilevel index, control 
information, and it can optionally contain free space. 

Free space can be distributed throughout the file and at the end of the 
file. Free space provides areas for inserting new records and is 
described later. 

In an indexed file, the records are arranged in ascending order by key. 
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DATA RECORD PRINARY KEY 



he primary key can be any field within your data record that you 
selects however, it must meet the following requi rements^ 

The selected field must start at the same location in each record 

All portions of the key field must be contiguous 

The primary key length cannot exceed 254 bytes 

The field must contain data that is unique within the data set. 



o 



Defining the Key 



Define a single key field by specifying its size and position in the 
record when you select the file formatting parameters using the SE (set 
parameter) command of the $IAriUTl utility. The longer the key, the 
larger the index. The key should not be longer than necessary but long 
enough to ensure uniqueness. A shorter key is more efficient than a 
long key. 

ENSURING UNIQUENESS OF THE KEY: To identify each record in an indexed 
file, each primary key must be unique. If key duplication is possible, 
the key field must be expanded to ensure that it is unique. 

For example, customer name is a key which may involve duplicates. To 
avoid duplication, lengthen the key field to include other characters 
such as part of the customer address or the account number. Because the 
characters in the key must be contiguous, you may need to rearrange the 
fields in the record. 

Another way to eliminate duplication is for you to modify new records 
dynamically whenever a duplication occurs during loading or processing. 
One or more characters at the end of the key field can be reserved for a 
suffix code. Whenever a duplicate occurs, add a value to the suffix and 
make another attempt to add the record to the file. The result is a 
file that can contain a sequence of keys such as SMITH, SMITHl, and 
SMITH2. If you add a suffix, you must use the entire unique key when 
accessing a record directly. 






Providing Access by More Than One Key 

To provide good performance with both direct and sequential access, each 
indexed file is indexed by a single primary key. At times, however, it 
may be useful to locate records by a secondary key. For example, in a 
customer file indexed by account number, you might want to locate a 
record by customer name. 

To provide access by a secondary key, you must build a secondary index 
(a separate file). For a description of setting up secondary indexes, 
see Chapter 5, "Building a Secondary Index" on page 5-1. 



c 
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RANDOM AND CLUSTERED RECORD INSERTS 

The Indexed Access Method permits records to be added to an existing 
file. The records are inserted by the Indexed Access Method in the 
proper locations according to their key value. This keeps the keys 
throughout the indexed file in ascending sequence. 

Records to be inserted are sometimes required to be distributed through- 
out the file rather evenly » other times the records to be inserted are 
in groups. 

Ulhen there are more individual records to be inserted throughout the 
file* based on their key value* than there are groups of records to be 
inserted* this is called random record inserts. The following diagram 
represents random inserted records among existing records. 



Exi sting 
Records 

Inserts 




























.Each bullet indicates an inserted record) 



Record inserts are considered clustered if most of the inserts occur at 
only certain places in the file. The following diagram represents clus- 
tered inserts by vertically stacked bullets. 
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DEFINING THE FILE STRUCTURE UITH $IAHUT1 




$IAMUT1 is a prompt driven utility. Ulhen it is loaded^ messages are 
displayed requesting information to be entered on a keyboard. The 
responses you enter through the keyboard determine hou the utility Mill 
operate. 

The SE command of the $IAMUT1 utility permits you to select one of three 
options for defining your indexed file. The parameter selections are 
made using the SE command of the $IAMUT1 utility. The SE (set parame- 
ters) command of $IAMUT1 provides three options for you to choose from 
to define your indexed file as follows: 

1. Option 1 significant parameters - allows you to define an indexed 
file by supplying a minimum of information. The description of your 
data records is required and whether you expect random or clustered 
record insert activity. 

2. Option 2 all parameters - allows more flexibility in precisely 
defining your indexed file but requires more parameters to be sup- 
plied. 

3. Option 3 parameters from existing indexed data set - can be used 
when you have an existing indexed file and you wish to use the same 
parameters for a new indexed file. 



$IAHUT1 Option Selection Guide 

Having read the preceding material » you are probably ready to make a 
choice as to which option you want to use in defining your indexed file 
The following table will help you to find the appropriate information, 
based on your indexed file defining objectives. 



Your objective 


Option 


Information location 


You want the Indexed Access 
Method to calculate and 
structure your f i le 


1 


See "Designing Indexed Files 
Using $IAMUT1 - Option 1" on 
page 3-5 


You want to structure a file 
and provide specific informa- 
tion for the parameters 


2 


See "Designing Indexed Files 
Using $IAMUT1 - Option 2" on 
page 3-7 


You want the Indexed Access 
Method to structure a file 
using the parameters of an 
exi sti ng f i le 


3 


See "Designing Indexed Files 
Using $IAMUT1 - Option 3" on 
page 3-35 



\J^' 
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DESIGNING INDEXED FILES USIKG ilAHUTl - OPTION 1 

Option 1 is used if you need to set up your indexed file quickly and 
easily. You specify only the necessary information and the utility 
determines the proper values for other parameters. An indexed file gen- 
erated Mith this option may not be optimum in terms of storage space 
performance. 

If you uant to supply more parameters than are available Mith this 
option* or you wish to set up a totally dynamic indexed file» you should 
see '^Designing Indexed Files Using $IAMUT1 - Option 2** on page 3-7. If 
you already have an indexed file established and you wish to use those 
same parameters* you should see "Designing Indexed Files Using $IAMUT1 - 
Option 3" on page 3-35. 



OPTION 1 

The Indexed Access Method utility* $IANUT1* option 1 of the SE (set 
parameters) command* provides you Mith the opportunity to select only 
those parameters necessary to set up an indexed file. 

The $IAMUT1 Indexed Access Method utility can be loaded Mith the Event 
Driven Executive operator command $L $IAHUT1. 

Uhen $IAMUT1 is loaded the first prompt displayed is as folloNS^ 



[13 ENTER COMMAND (?): SE 



^pw^i^ 



[11 Entering SE causes the folloMing option list prompt to be displayed. 



[2] 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATA SET 
ENTER OPTION: 1 






[21 Respond to this prompt by entering the digit *1*. This response 
causes a one line prompt from the next prompt sequence to be displayed. 

Note: Although the folloMing prompts are displayed one line at a time 
Mhen using the utility* the entire prompt list is shoMn for simplicity 
in describing the parameters. 
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[33 

[4] 
[53 
[63 
[73 
[83 
[93 
[103 



[113 



SECONDARY INDEX (Y/N)?: N 






DEFAULT NEW VALUE 


RECORD SIZE 


0:80 


KEY SIZE 


0:40 


KEY POSITION 


1:1 


BLOCKING FACTOR (RECORDS PER BLOCK) 


1:3 


NUMBER OF BASE RECORDS 


0:5 


ESTIMATED TOTAL RECORDS 


6:20 


TYPE OF INSERT ACTIVITY(C=CLUSTERED, 


R=RANDOM) C:R 


DATA SET SIZE IN EDX RECORDS: 


11 


INDEXED ACCESS METHOD RETURN CODE: 


-1 


SYSTEM RETURN CODE: 


-1 


CREATE/DEFINE FILE (Y/N)?: 





[33 The first line asks» are you specifying a secondary index. The 
response should be N for no» because you are defining the parameters for 
a primary index file. 

[43 The record length shown is 80» however^ the entry you Mill make is 
the actual record length you want your indexed file records. 

[53 Enter the length of your data record field that you arB using as the 
key field. The maximum primary key length is 254. 

[63 Enter the position where your primary key field begins. Your data 
record begins with 1. 

[73 Specify the blocking factor (number of records per block) you want 
your indexed file to have. Remember that when a record is accessed^ an 
entire block is actually read into the system buffer. 

[83 Enter the number of base record slots to be defined. This value is 
the number of records you will load initially. You cannot load more 
records than this value specifies. 

[93 Enter the total number of records you expect this file to contain. 
This includes records that you plan to insert during processing. 

[103 Enter the type of record insert activity you expect to have 

[113 If you have verified that the parameters you entered are correct* 
the data set (file) size in EDX records is acceptable* and the return 
codes are both -1, you can reply Y and you can create and define the 
file. If you wish to change any of the parameters* reply N and you can 
reenter the SE command and enter any new values for the parameters. 

Replying N terminates the SE function and you can return to this point 

by reentering the SE command or the DF command (within the same session 

of $IAMUT1). The DF command of $IAMUT1 is described under "DF — Define 
Indexed File" on page 9-6. 

To review the prompts that occur when Y is replied at this point return 
to the example in Chapter 2, "Using the Indexed Access Method." 



\^_jj 
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DESIGNIKG INDEXED FILES USING $IAMUT1 - OPTION 2 

Option 2 is used if you have performed an analysis of your file require- 
ments and you Nant to precisely define your primary indexed file. This 
option provides a Mide range of parameters to alloM you to specify your 
file structure in detail. You can optimize the file structure according 
to your application requirements for the best storage use and perform- 
ance. 

If you Mant to supply only the minimum parameters you might want to use 
option 1 which is described earlier in this chapter under "Designing 
Indexed Files Using $IAMUT1 - Option 1" on page 3-5. If you already 
have an indexed file established and you wish to use those same parame- 
ters» you should see '^Designing Indexed Files Using $IAMUT1 - Option 3** 
on page 3-35. 



OPTION 2 

The following information is provided so that you can supply the 
required information to the prompts when defining a primary index file 
using option 2 of $IAMUT1. The information is organized in levels of 
Indexed Access Method blocks. The material should be read sequentially 
because it provides the information which must be understood in order to 
apply it to the examples which are placed near the end of this option 2 
material . 



INDEXED ACCESS HETHOD BLOCKS 

Indexed files consist of three kinds of blocks^ 

• Data blocks^ which contain records 

• Index blocks^ which contain pointers to data blocks or lowei — level 
index blocks 

• File control blocks^ which contain control information. 

Following is an overview diagram showing the types of blocks and their 
general relationships to each other in an indexed file. 
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Figure 3-1. Indexed File Logical Structure 
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The indexed file is composed of a number of fixed length blocks. The 
block is the unit of data transferred by the Indexed Access Method 
betMeen disk/diskette and the central buffer. Block size must be a mul- 
tiple of 256. A block is addressed by its relative block number (RBN). 
The first block in the file is located at RBN 0. 

Note that the RBN is used only in indexed files by the Indexed Access 
Method. An Indexed Access Method block differs from an Event Driven 
Executive record in the following ways* 

1. The size of a block is not limited to 256 bytes; its length can be a 
multiple of 256. 

2. The RBN of the first block in an indexed file is 0. The record num- 
ber of the first Event Driven Executive record in a file is 1. 

The size» in 256-byte records* of the file is calculated by the SE com- 
mand of the $IAMUT1 utility. 

As stated initially* three kinds of blocks exist in an indexed file^ 
data blocks* index blocks* and file control blocks. These blocks are 
all the same length* as defined by BLKSIZE* but they contain different 
kinds of information. Data blocks contain data records* index blocks 
contain index entries* and file control blocks contain control informa- 
tion. 



DATA BLOCKS 



c 



Each data block contains a header* one or more data records* and it can 
contain free space for additional data records. 

The records in each data block are in ascending order* according to the 
key field in each record. 

Each data block header contains the address of the next sequential data 
block* providing sequential processing capability. 

A data block contains a header followed by data records. The number of 

records that can be contained in a data block depends on the size of the 

data block and the size of the record. The header of the block is 16 
bytes. 

The number of record areas in the block is^ 



block size - 16 
record size 



The result is truncated* any remainder represents the number of unused 
bytes in the block. For example* if block size is 256 and record size 
is 80* the data block can accommodate three records and there is no 
unused area. The key field of the last record slot in an index block is 
the high key for the data block even if the block is not full. 
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Houiever» if the last record of the block has been deleted^ the key field 
of the last record slot will contain a key higher than that of any other 
record in the block. Deletion of a record does not reduce the key range 
for the block unless the block is emptied. Figure 3-2 » shouis the for- 
mat of a data block. 
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FREE SPACE 



Uhen an indexed file is loaded Mith base records^ free space is reserved 
for records that may be inserted during processing. There are four 
kinds of free space: free records^ free blocks> reserve blocks^ and 
reserve index entries. 

FREE RECORDS: Free records are areas reserved at the end of each data 
block. The FREEREC parameter of the SE command of $IAMUT1, specifies 
the number of free records that ar& reserved in each data block. The 
remaining record areas are called allocated records. 

For example> if a block contains three data record areas and you specify 
one free record per blocks then there are two allocated records per 
block. For the layout of a data block containing two allocated records 
and one free record, see Figure 3-2. 

Uhen records are loaded (file is open in load mode)> the allocated 
records are filled* and the free records are skipped. Ulhen additional 
records are inserted (file is open in process mode)* free records are 
used to hold inserted records. 



HEADER 


Data 


Record 


Data 


Record 


Free 


space 






Figure 3-2. Data Block Format Example 

For an example of specifying FREEREC, see "Example 1: Allocating Free 
Records" on page 3-24. 

FREE BLOCKS: Free blocks follow the allocated data blocks within each 
cluster. Free blocks have all of their records marked as free records. 
The FREEBLK parameter of option 2 is used to specify the percentage of 
blocks that are to be marked as free blocks. 

Ulhen records are loaded* the allocated record areas in the allocated 
data blocks are filled, and the free blocks are skipped. During proc- 
essing, as data blocks become full, a free block provides space for 
i nsert i ons. 

For an example of specifying FREEBLK, see "Example Z- Allocating Free 
Records and Free Blocks" on page 3-26. 



o 
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SEQUENTIAL CHAINING^ Data blocks in an indexed file are chained together 
by forward pointers located in the headers of data blocks. Only allo- 
cated data blocks are included in the sequential chain. Chaining pro- 
vides for sequential processing of the file with no need to reference 
the index. Uhen a free block is converted to an allocated blocks the 
free block is included in the chain. 



Reserving Space For Record Inserts 

If base records are to be loaded and record insertions are expected in 
random locations throughout the file» use BASEREC to reserve the number 
of base records. Use some combination of the following parameters^ 
FREEREC to reserve free records in each data blocks FREEBLK to reserve 
free blocks in each cluster (group of blocks), and DYN to provide a free 
pool . 

For example, consider a file with 5 records per block, and 10 data 
blocks per cluster. Suppose that the file consists of 300 base records 
and 200 inserts. 

If the inserts are distributed evenly throughout the file, the pattern 
of inserts is^ 









Blocks 
























Inserts 
(Ei 


jch bullet indicates an inserted record) 





With this kind of distribution you can specify 2 free records per block 
to absorb the inserts; no free blocks or free pool are needed. 

Of course inserts do not usually occur in such an even pattern. Free 
blocks help to absorb a concentration of inserts. The more uneven the 
expected distribution, the greater the free block specification should 
be. 

Suppose the same number of inserts is distributed in this pattern- 









Blocks 
























Inserts 








With this distribution, specify either 3 free records per block, or 20% 
free blocks with 2 free records per block. 
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NoM suppose the distribution Mere more uneven 
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In this case a satisfactory mix of free space is 1 free record per block 
and 40% free blocks. An alternative is to use 1 free record per block 
and the DYN parameter to hold those record inserts of more than 1 record 
per block. 



Calculating Data Blocks 

This calculating information is provided for your convenience if you 
choose to calculate the number of blocks for a specific file. For ref- 
erence later there is a summary of all calculations in Appendix 
A, "Summary of Calculations" on page A-1. However, $IAMUT1 automat- 
ically calculates the required data blocks based on the parameters you 
provide. The utility also lists at file definition time (when using the 
SE command) the number of blocks required according to your parameter 
values. 

The number of allocated data blocks in a file is the specified number of 
base records (BASEREC) divided by the number of allocated records per 
data block, with the result rounded up if there is a remainder. 

For example, suppose you intend to load 1000 records in an indexed file 
that is formatted for two allocated records and one free record per 
block and five allocated blocks and one free block per cluster. The 
number of allocated blocks in a file is! 



o 



number of base records 

number of allocated records per block 



The number of allocated blocks in this example is 1000/2 or 500 blocks. 
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INDEX BLOCKS 



An index block contains a 
Each index entry consists 
est key associated Mith a 
that block. The number of 
on block size and key size 
RBN field in each entry is 
an even number of bytes in 
bytes in lengths the field 
number of index entries in 



header folloMed by a number of index entries, 
of a key and a pointer. The key is the high- 
loMer level block; the pointer is the RBN of 
entries contained in each index block depends 

The header of the block is 16 bytes. The 
4 bytes. The key field in each entry must be 
length; if the key field is an odd number of 
is padded uiith one byte to make it even. The 
an index block is" 



block size - 16 
4 + key length 



The result is truncated; any remainder represents the number of unused 
bytes in the block. 



or example^ if block size is 256 and key length is 28» th 
intry is 32 bytes, there are 7 entries in a block, and the 
f the block are unused. 



then each index 
last 16 bytes 



PRIMARY INDEX BLOCKS (PIXB) 

A set of data blocks is addressed (described) by a single primary index 
block (PIXB). Each key in the index block is the highest key in the 
data block that its accompanying relative block number (RBN) addresses. 
A block is addressed by its RBN. The PIXB and the data blocks it 
describes are called a cluster. 



Clusters 



Primary-level index bl 
file in groups called 
primary-level index bl 
points to. For exampl 
there are eight blocks 
up to 7 data/free bloc 
blocks represented by 
insert activity has ta 
obtained from the free 
an index block and one 
cluster consists of se 
See Figure 3-3 on page 



ocks and data blocks are stored 
clusters. Each cluster consists 
ock and as many data blocks and 
e, if there are seven entries in 

in a cluster? one primary-level 
ks. If reserve blocks have been 
the reserve block entries are no 
ken place and the required block 

pool. For example, if there ar 

of the entries is a reserve bio 
ven blocks (one index block and 

3-14 for a cluster example. 



together in the 
of a 

free blocks as it 
an index block, 
index block and 
specified, the 

t included until 

s have been 

e seven entries in 

ck entry, the 

six data blocks). 
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PIXB 



HEADER 


RBN of 
block 1 


High key 
in block 1 


RBN of 
block 2 


High key 
in block 2 


RBN of 
block 3 


High key 
in block 3 



RBN of 
block 7 



High key 
in block 7 



( 



Data 
blocks 



• • • 



Figure 3-3. Cluster Example 



Primary-Level index Blocks 



'%.-^ 



Entries in a primary-level index block point to data blocks. Each entry 
in a primary-level index block is one of three possible typesJ 

• Allocated entry 

• Free block entry 

• Reserve block entry. 

ALLOCATED ENTRY! An allocated entry points to an active data block. The 
key portion of the entry is initialized to binary ones by the §IAMUT1 
utility. After records have been loaded or written to a data block* the 
key portion of the entry Mhich points to the data block contains the 
highest key from the data block. 

The pointer portion contains the RBN of the data block. Allocated 
entries are the first entries in an index block. The number of index 
entries allocated, Mhen the indexed file is initially created* is the 
total number of entries per index block, less the number of entries of 
the other two types (free block entry and reserve block entry). 



o 
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FREE BLOCK ENTRY-' A free block entry points to a free data block. The 
key portion of the entry contains binary zeros. The pointer portion 
contains the RBN of the free block. Free block entries folloM the allo- 
cated entries in the index block. The number of index entries formatted 
as free entries when the indexed file is initially created is the speci- 
fied percentage (FREEBLK) of the total number of entries in an indexed 
blockf Nith the result rounded up if there is a remainder. 

RESERVE BLOCK ENTRY: A reserve block entry does not point to a block but 
is reserved for later use as a pointer to a data block which can be tak- 
en from the free pool. Both the key and pointer portions of a reserve 
block entry are binary zeros. Reserve block entries are at the end of 
the index block. When a reserve block entry is converted to a used 
entry* the index block is reformatted to move the entry to the allocated 
entry area of the block. 

Reserve blocks do not exist in the cluster. Uhen all data blocks in a 
cluster are used and another data block is needed* a data block can be 
created from the free pool. If the primary-level index block contains a 
reserve block entry* it is used to point to the record from the free 
pool. The reserve block entry in the primary-level index block points 
to the block* and the data block becomes an allocated data block. 

The number of index entries initially formatted as reserve block entries 
is the specified percentage (RSVBLK) of the total number of entries* 
with the result rounded up if there is a remainder. However* if the 
number of free block entries plus the number of reserve block entries 
require all index entries* the number of reserve block entries is 
reduced by 1* providing at least one allocated entry per index block. 

To calculate the number of primary-level index blocks in an indexed 
file* you must know the initial number of data blocks allocated in the 
indexed file. 



Calculating Clusters 

This calculating information is provided for your convenience if you 
choose to calculate the number of blocks for a specific file. However* 
$IAMUT1 automatically calculates the required data blocks based on the 
parameter values you provide. The utility also lists at file definition 
time (when using the SE command) the number of blocks required according 
to your parameter values. 

The number of clusters in a file is the number of allocated data blocks 
divided by the number of allocated entries in each primary-level index 
block* with the result rounded up if there is a remainder. 



allocated blocks 

allocated entries in each PIXB 



O 



Note that in the calculation* if the quotient is not an integer* it is 
rounded up (rather than truncated) in order to accommodate all of the 
base records. 
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The number of free blocks in the file (not including the free pool) is 
the number of clusters in the file multiplied by the number of free 
entries in each primary-level index block. 



The Last Cluster 



The last cluster in the file may be different from the other clusters. 
It contains the same number of free blocks as the other clusters but 
only enough allocated blocks to accommodate the records that you have 
specified Mith the parameter BASEREC. Because rounding occurs in calcu- 
lating the number of clusters* a feM more allocated records than 
required may exist in the last allocated block. The last cluster can be 
a short one because only the required number of blocks are used. 

If the number of allocated blocks divided by the number of allocated 
blocks per cluster leaves a remainder » the remainder represents the num- 
ber of allocated entries in the primary-level index block in the last 
cluster. Unused entries in the last primary-level index block are 
treated as reserve block entries. 

The initial number of data blocks is the specified number of base 
records (BASEREC) divided by the number of allocated records in a data 
block* with the result rounded up if there is a remainder. 



BASEREC 

data records per block 



The number of primary-level index blocks is the initial number of allo- 
cated data blocks divided by the number of allocated entries per 
primary-level index block* with the result rounded up if there is a 
remai nder . 



K^ 



allocated data blocks 

allocated entries per primary-level index block 



c 
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SECOND-LEVEL INDEX BLOCKS (SIXB) 

If the file is large enough to require more than one cluster » each PIXB 
(or cluster) has an entry in a second-level index block (SIXB). The 
entry in a SIXB contains the address of the PIXB and the highest key in 
the cluster. The SIXB has the following structure^ 



SIXB 



HEADER 


RBN of 
PIXBl 


High key 
in PIXBl 


RBN of 
PIXB2 


High key 
in PIXB2 


RBN of 
PIXB3 


High key 
in PIXB3 


RBN of 
PIXB4 


High key 
in PIXB4 






PIXBl 



PIXB2 



PIXB3 



PIXB^ 



Entries in a second-level index block point to primary-level index 
blocks. Each entry in a second-level index block is one of two possible 
types* 

• Allocated entry 

• Reserve index entry. 

ALLOCATED ENTRY J An allocated entry points to an existing primary-level 
index block. The key portion of the entry is initialized to binary ones 
by the $IAMUT1 utility. After records have been loaded or written, the 
key portion of the entry contains the highest key from the primary-level 
index block. The pointer portion contains the RBN of the primary-level 
index block. Allocated entries are the first entries in the index 
block. The number of index entries allocated when the indexed file is 
loaded is calculated as the total number of entries per index block, 
less the number of reserve index entries. 
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RESERVE INDEX ENTRY: A reserve index entry does not point to a block but 
is reserved for later use as a pointer to a primary-level index block 
that can be taken from the free pool. Both the key and pointer portions 
of a reserve index entry are binary zeros. 



o 



Reserve index entries* in second-level 
for the index structure to be expanded 
blocks. These* in turn* can have data 
forming new clusters. This process of 
cluster split . 



index blocks* provide index space 
by adding new primary-level index 
blocks associated with them* thus 
forming a new cluster is called a 



For an example of using RSVIX* refer to "Example 4 
Index Entries" on page 3-30. 



Allocating Reserved 



Reserve index entries are at the end of the index block. The number of 
index entries initially formatted as reserve index entries is the speci- 
fied percentage (RSVIX) of the total number of entries* with the result 
rounded up if there is a remainder. However* if the number of reserve 
index entries is the same as the total number of entries in an index 
block* the number of reserve index entries is reduced by 1* providing at 
least one allocated entry per second-level index block. 

The number of second-level index blocks is the number of primary-level 
index blocks divided by the number of allocated entries per second-level 
index block* with the result rounded up if there is a remainder. 



number of PIXBs 

allocated entries per SIXB 






o 
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HIGHER-LEVEL INDEX BLOCK (HIXB) 

If the file is large enough to require more than one SIXB» the SIXBs in 
the file are described by one or more higher-level index blocks (HIXB) 
in the same manner as the SIXB describes PIXBs. There is always one 
index block that describes the entire file. 

The index of an indexed file is constructed in several levels so that» 
given a key, there is a single path (one index block per level) cascad- 
ing through the index levels that leads to the data block associated 
with that key. The index is built from the bottom up. At the lowest 
level are the primary-level index blocks. At the second level are index 
blocks containing entries that point to the primary-level index blocks. 
The highest level of the index structure consists of a single index 
block. 



c 



Entries in a higher-level index block point to index blocks at the next 
lower level. All entries in highei — level index blocks are allocated 
entries. The key portion of the entry contains the highest key from the 
index block of the next lower level. The pointer portion contains the 
RBN of the next lower level index block. The number of blocks at any 
higher index level is the number of index blocks at the next lower level 
divided by the total number of entries per index block, with the result 
rounded up if there is a remainder. 

If the number of index blocks at any level is one, that level is the top 
level of the index. Although the Indexed Access Method is capable of 
initially defining and supporting 17 levels of index, an indexed file is 
formatted with only as many index levels as are required for the number 
of records. If an indexed file has not been fully loaded and one or 
more higher index levels have not yet been required, the unnecessary 
higher levels are not used, even though they exist in the file 
structure. 

INDEX EXAMPLE: Assume that 500 data blocks are allocated to a file and 
that each primary-level index block contains one free block entry, one 
reserve block entry, and five allocated entries. Therefore, the total 
number of primary-level index blocks is 100. Each second-level index 
block contains one reserve index entry and six allocated entries; there- 
fore, the number of second-level index blocks is 17. The number of 
entries in higher level index blocks is seven, resulting in three index 
blocks at the third level and one at the fourth level. 



Therefore the file contains a total of 121 index blocks of which 100 are 
primary-level index blocks, 17 are second-level index blocks, 3 sre 
third-level index blocks, and 1 is a fourth-level index block. This 
distinction is important because high-level index blocks are located 
contiguously at the beginning of the file (after the FCB), while 
primary-level index blocks are scattered throughout the file with the 
data blocks. Figure 3-^ shows the structure of the highei — level index 
blocks. 



o 



Fourth 
(top) 
level 
i ndex 



Third 
level 
i ndex 



Second 

level 

index 



Figure 3-4. High-level Index Structure 
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FREE POOL 



If you specify that you Mant a free pool> your indexed file contains a 
pool of free blocks at the end of the indexed file. The file control 
block contains a pointer to the first block of the free pool» and all 
blocks in the free pool are chained together by forward pointers. 

A block can be taken from the free pool to become either a data block or 
an index block. The block is taken from the beginning of the chain* and 
its address (RBN) is placed in the appropriate primary-level index block 
(if the new block is to become a data block) or in the second level 
index block (if the new block is to become a primary-level index block)* 
and so on. Any block in the free pool can be used as either a data 
block or as an index block. 

Mhen a data block becomes empty because of record deletions* the data 
block may return to the free pool (depending on the delete threshold 
( DEITHR ) parameter). If the data block is returned to the free pool* 
reference to the block is removed from the primary-level index block* 
and the block is placed at the beginning of the free pool chain. 

Calculating the initial size of the free pool consists of the following 
stepsJ 

• Each reserve block entry in a primary-level index block represents a 
potential data block from the free pool. The number of data blocks 
that can be assigned to initial clusters is the number of 
primary-level index blocks times the number of reserve block entries 
in each primary-level index block. 

• Each reserve index entry in a second-level index block represents a 
potential primary-level index block from the free pool. The number 
of primary-level index blocks that can be assigned from the free 
pool into the index structure set up at file definition time is the 
number of second-level index blocks multiplied by the number of ,4^^ 
reserve index entries in each second-level index block. 



• Each primary-level index block taken from the free pool consists 
entirely of empty (reserve block) entries. New data blocks can be 
taken from the free pool for the entries in the new primary-level 
index block. The number of data blocks is the number of entries per 
index block multiplied by the number of new primary-level index 
blocks (calculated in the previous step). 

• The maximum number of blocks that can be taken from the free pool 
and placed into the index structure set up at file definition time 
is the sum of the previous three calculations. 

• The actual number of blocks in the free pool is determined in one of 
two ways* 

— The percentage (FPOOL) of the maximum possible free pool as 
specified by the RSVIX and RSVBLK parameters. The result is 
rounded up if there is a remainder. If the DYN parameter is 
also used* its value is added to the sum. 

— The DYN parameter* if specified with no other free space parame- 
ters* allocates a free pool of the specified number of blocks. 

DELTHR - DELETE THRESHOLD: The percentage (0-99) of blocks to retain in 
a cluster as records are deleted and blocks made available. This is 
known as the delete threshold DELTHR. When a block becomes empty* this 
parameter* if supplied* determines if the block should be returned to 
the free pool. 



A„y 



3-20 SC34-0771 



pyyg CQNTRQi, gypcK 



The file control block (FCB) is the first block in the file (RBN 0); it 
contains control information. 

Indexed files have an FCB Extension as the second block. The FCB Exten- 
sion contains the parameters used to define the file. 

Note: Indexed files built Mith a version of the Indexed Access Method 
prior to version 2 do not contain an FCB extension. 

You can access the FCB and FCB Extension by either of the following 
methods: 

• Using the EXTRACT function in an EDL program 

• Using the $VERIFY utility. 

You can locate the field names in the FCB and FCB Extension by examining 
a listing of FCBEQU/ a copy code module that is supplied as part of the 
Indexed Access Method. The FCB Extension contains the parameters that 
Mere used to set up the file using the $IAMUT1 SE command. Control 
information is also contained in block headers; a description of control 
information is contained in "FCB Extension Report" on page 10-8. 



FILE STRUCTURE TYPES 



o 



A Mide range of file structure is available. You can set up files that 
vary from the totally dvnami c to the highly structured . Whether a file 
is structured or dynamic depends on the degree to which it uses a free 
pool - 

A free pool is an area in your indexed file which contains a pool of 
free blocks. The file control block contains a pointer to the first 
block of the free pool» and all blocks in the free pool are chained 
together by forward pointers. A block can be taken from the free pool 
to become either a data block or an index block. 

Dynamic files offer the advantage of easy file design and good space 
utilization. They have the disadvantage of a potential performance 
decrease. 

Structured files offer the advantage of good performance. They have the 
disadvantage of a more complex file design and greater space require- 
ments. 

Either method can result in a need to reorganize the file; the struc- 
tured approach because the file can run out of space for inserts^ and 
the dynamic approach because of performance considerations. 

The type of indexed file to be defined* structured or dynamic* 
therefore* depends on the file requirements and the efficiency required. 



Structured File 

A structured file has its base record slots* free space* and the index 
structure needed to support them built at file definition time by the 
Indexed Access Method utility using the file structure parameters you 
specify. The structured file uses little* if any* free pool. The 
structured file offers better performance than the dynamic file but can 
result in unused space. 



Chapter 3, Defining Primary Index Files 3-21 



Uhether or not a structured file has a free pool depends on whether or 
not you supply a value for the DYN parameter when the file is defined. 
When the DYN parameter is used, the FREEREC, FREEBLK, RSVBLK, RSVIX, and 
FPOOL parameters, if supplied, are also used in establishing the struc- 
tured free space. The number and types of blocks in a structured file 
are the result of calculated values you supply as parameters Mhen defin- 
ing the file. Most of the blocks are not taken dynamically from the 
free pool as they are needed because they are established at file defi- 
nition time. 



Dynamic File 

The higher the degree to which a file uses a free pool, the more dynamic 
it is; the system builds index and data blocks for you as they are 
needed. 

The Indexed Access Method provides a dynamic file restructuring capabil- 
ity. It makes use of any free pool space the file has, even if the file 
is mostly structured. 

The Indexed Access Method can restructure a file in two ways: 

• As records ar& inserted and additional space is needed in specific 
areas of the file, blocks are taken from the free pool and become 
data blocks where needed. If additional index blocks are needed, 
blocks are taken from the free pool for this purpose as well. Index 
blocks can be added at any level, and the number of levels of index 
can increase as needed. This function is performed automatically by 
the Indexed Access Method on any file that has a free pool associ- 
ated with it. 

• As records are deleted and blocks become empty, they are returned to 
the free pool. If index blocks become empty (because the blocks 
under them have been returned to the free pool) they are also 
returned to the free pool. This helps to maintain a supply of 
blocks in the free pool to be used if other areas of the file 
expand. 

For an example of defining a totally dynamic file, see "Example 5 - 
Defining a Totally Dynamic File" on page 3-33. 

USING THE DYN PARAMETER: The DYN parameter can be used to adjust how 
much the free pool is used. This adjustment varies how dynamic a struc- 
tured file is. 

In a totally dynamic file, the initial file defined consists of only the 
file control blocks, one primary index block and one data block. The 
rest of the file is in the free pool. 

To define a totally dynamic file, you need to only supply a value for 
the DYN parameter to allow the rest of the file to be assigned to the 
free pool. 

A dynamic file can be used when the records you want to add to the file 

are not sorted into ascending key sequence. In that case, you can place 

the records in the file by inserting them in random sequence. The 

Indexed Access Method will place them in their proper sequence within 
the indexed file. 

If base records are to be loaded initially and they are sorted in 
ascending key sequence but insert activity is unknown, you can use a 
totally dynamic file design. Use the BASEREC parameter to reserve the 
number of base record slots required. Use the DYN parameter to provide 
the free pool needed for record inserts. 

Note: yhen a dynamic file has grown to its working size, it should be 
reorganized for more efficient operation. 



/if ^, 
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OPTION 2 EXAMPLES 



The examples Mhich folloM are provided to shoM the option 2 prompts and 
the effects of certain parameter values. Although the values used are 
small for simplicity of explanation, they are usually much larger in an 
actual application. Also a given example does not represent a complete 
primary index file but addresses a particular part of a file and its 
associated parameters Mhich ue Ni sh to describe at that place in the 
chapter. 
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EXAHPLE l: ALLOCATING FREE RECORDS 



The indexed file created using these parameters has only one type of 
free space> called free records^ 



,.>^ 



CI] 



ENTER COMMAND (?): SE 




SET FILE DEFINITION PARAMETERS 




= EXIT 




1 = SIGNIFICANT PARAMETERS 




2 = ALL PARAMETERS 




3 = PARAMETERS FROM EXISTING INDEXED DATASET 




ENTER OPTION: 2 




SECONDARY INDEX (Y/N)?: N 




PARAMETER DEFAULT NEW VALUE 




BASEREC NULL 


10 




BLKSIZE 


25S 




RECSI2E 


80 




KEYSI2E 


40 




KEYPOS 1 


1 




FREEREC 


1 




FREEBLK 







RSVBLK NULL 






RSVIX 






FPOOL NULL 






DELTHR NULL 






DYN NULL 






TOTAL LOGICAL RECORDS/DATA BLOCK: 


3 


FULL RECORDS/DATA BLOCK: 


2 


INITIAL ALLOCATED DATA BLOCKS: 


5 


INDEX ENTRY SIZE: 


44 


TOTAL ENTRIES/INDEX BLOCK: 


5 


FREE ENTRIES/PIXB: 





RESERVE ENTRIES/PIXB(BLOCKS): 





FULL ENTRIES/PIXB: 


5 


RESERVE ENTRIES/SIXB: 





FULL ENTRIES/SIXB: 


5 


DELETE THRESHOLD ENTRIES: 


5 


FREE POOL SIZE IN BLOCKS: 





# OF INDEX BLOCKS AT LEVEL 1: 


1 


DATA SET SIZE IN EDX RECORDS: 


8 


INDEXED ACCESS METHOD RETURN CODE: 


-1 


SYSTEM RETURN CODE: 


-1 


CREATE/DEFINE FILE (Y/N)?: N 




ENTER COMMAND (?): 
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[1] Because record size Mas specified as 80 and block size Mas specified 
as 256, there are (256-16)/80 = 3 records per block. Because FREEREC 
was specified as 1, there are 2 full (base) records per block and 1 free 
record per block. Because BASEREC Mas specified as 10, there are 10/(2 
base records per block) or 5 initial allocated data blocks (blocks that 
contain base records). Because FREEBLK, RSVBLK, R5VIX, FPOOL, and DYN 
were not specified, there are no free blocks or free pool blocks allo- 
cated. One primary index block is needed. 



The number of free blocks is calculated as folloMs: 
PIXB times the number of index blocks at level 1. 



Free entries per 



The total blocks allocated for this file is* 



Initial allocated data blocks 

Free blocks 

Free pool blocks 

Index blocks 

File control block 



5 


1 
2 
8 Total 



Figure 3-5 illustrates the format of the indexed file that Mould result 
from these SE command parameters. 
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Figure 3-5. Indexed File Mith Free Records 
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EXAMPLE 2: ALLOCATING FREE RECORDS AND FREE BLOCKS 

These parameter specifications Mill generate an indexed file with two 
types of free space — free records and free blocks^ 



o 



[1] 



ENTER COMMAND (?): SE 




SET FILE DEFINITION PARAMETERS 




= EXIT 




1 = SIGNIFICANT PARAMETERS 




2 = ALL PARAMETERS 




3 = PARAMETERS FROM EXISTING INDEXED DATASET 




ENTER OPTION: 2 




SECONDARY INDEX (Y/N)?: N 




PARAMETER DEFAULT NEW VALUE 




BASEREC NULL 


10 




BLKSI2E 


256 




RECSIZE 


80 




KEYSI2E 


40 




KEYPOS 1 


1 




FREEREC 


1 




FREEBLK 


10 




RSVBLK NULL 






RSVIX 






FPOOL NULL 






DELTHR NULL 






DYN NULL 






TOTAL LOGICAL RECORDS/DATA BLOCK: 


3 


FULL RECORDS/DATA BLOCK: 


2 


INITIAL ALLOCATED DATA BLOCKS: 


5 


INDEX ENTRY SIZE: 


^^ 


TOTAL ENTRIES/INDEX BLOCK: 


5 


FREE ENTRIES/PIXB: 


1 


RESERVE ENTRIES/PIXBCBLOCKS): 





FULL ENTRIES/PIXB: 


4 


RESERVE ENTRIES/SIXB: 





FULL ENTRIES/SIXB: 


5 


DELETE THRESHOLD ENTRIES: 


5 


FREE POOL SIZE IN BLOCKS: 





« OF INDEX BLOCKS AT LEVEL 1: 


2 


# OF INDEX BLOCKS AT LEVEL 2: 


1 


DATA SET SIZE IN EDX RECORDS: 


12 


INDEXED ACCESS METHOD RETURN CODE: 


-1 


SYSTEM RETURN CODE: 


-1 


CREATE/DEFINE FILE (Y/N)?: n 




ENTER COMMAND (?): 





\J 



[1] The FREEBLK parameter of 10 causes 10% of the total entries in each 
index block to point to free blocks. Because KEYSIZE was specified as 
^0, the index entry size =40+4 (RBN pointer) and the total entries 
per index block is (256-16)/44 = 5. Thus, 10% of this total rounded up 
is the number of free entries/PIXB (1). Because there are 5 initial 
allocated data blocks, one free entry and only 5 total entries per index 
block, 2 primary index blocks are needed. This causes a second-level 
index block to be allocated. 
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The total blocks allocated: 



Initial allocated data blocks 

Free blocks 

Free pool blocks 

Index blocks 

Fi le control block 



5 
2 


3 
+ 2 
12 Total 



Figure 3-6 illustrates the format of the indexed file that Mould result 
from these SE command parameters. 
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Figure 3-6. Indexed File with Free Records/Blocks 
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EXAMPLE 3: ALLOCATING RESERVED DATA BLOCKS 

Reserve blocks are allocated using the RSVBLK and FPOOL parameters of 
the SE command. The folloMing SE command example shous the specifica- 
tion of an indexed file with reserved data blocks. 



O 



CI] 
[2] 



ENTER COMMAND (?): SE 




SET FILE DEFINITION PARAMETERS 




= EXIT 




1 = SIGNIFICANT PARAMETERS 




2 = ALL PARAMETERS 




3 = PARAMETERS FROM EXISTING INDEXED DATASET 




SECONDARY INDEX (Y/N)?: N 




ENTER OPTION: 2 




PARAMETER DEFAULT NEW VALUE 




BASEREC NULLaO 




BLKSIZE 0:256 




RECSIZE 0:80 




KEYSIZE 0:40 




KEYPOS 1:1 




FREEREC 0:1 




FREEBLK 0:10 




RSVBLK NULL: 10 




RSVIX 0: 




FPOOL NULL:50 




DELTHR NULL: 




DYN NULL: 




TOTAL LOGICAL RECORDS/DATA BLOCK: 


3 


FULL RECORDS/DATA BLOCK: 


2 


INITIAL ALLOCATED DATA BLOCKS: 


5 


INDEX ENTRY SIZE: 


44 


TOTAL ENTRIES/INDEX BLOCK: 


5 


FREE ENTRIES/PIXB: 


1 


RESERVE ENTRIES/PIXBCBLOCKS): 


1 


FULL ENTRIES/PIXB: 


3 


RESERVE ENTRIES/SIXB: 





FULL ENTRIES/SIXB: 


5 


DELETE THRESHOLD ENTRIES: 


4 


FREE POOL SIZE IN BLOCKS: 


1 


» OF INDEX BLOCKS AT LEVEL 1: 


2 


# OF INDEX BLOCKS AT LEVEL 2: 


1 


DATA SET SIZE IN EDX RECORDS: 


13 


INDEXED ACCESS METHOD RETURN CODE: 


-1 


SYSTEM RETURN CODE: 


-1 


CREATE/DEFINE FILE (Y/N)?: n 




ENTER COMMAND (?): 








CI] In this example RSVBLK was specified as 10. Thus lOX of the total 
entries in each PIXB will initially be reserved. 

[2] Because the total entries per PIXB is 5, 10% of 5 rounded up will 
cause 1 entry in each PIXB to be reserved. Because there are Z PIXBs* 
each with 1 reserve entry, a maximum of 2 free pool blocks can be used. 
However, since FPOOL was specified as 50%, only half of these blocks (1 
block) will be allocated for the free pool. 

The total blocks allocated for this file is: 



Initial allocated data blocks 

Free blocks 

Free pool blocks 

Index blocks 

File control block 



5 
2 
1 
3 
+ 2 
13 Total 



c 



Figure 3-7 on page 3-29 illustrates the format of the indexed file that 
would result from these SE command parameters. 
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Figure 3-7. Indexed File with Reserved Data Blocks 
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EXAMPLE 4: ALLOCATING RESERVED INDEX ENTRIES 



In the folloMing example/ the index structure is set up to use free pool 
blocks for index blocks by allocating reserve index entries using the 
RSVIX parameter. 



J 





ENTER COMMAND (?): SE 






SET FILE DEFINITION PARAMETERS 






= EXIT 






1 = SIGNIFICANT PA1?AMETERS 






2 = ALL PARAMETERS 






3 = PARAMETERS FROM EXISTING INDEXED DATASET 






ENTER OPTION: 2 






SECONDARY INDEX (Y/N)?: N 






PARAMETER DEFAULT NEW VALUE 






BASEREC NULL: 10 






BLKSIZE 0:256 






RECSIZE 0:80 






KEYSIZE 0:40 






KEYPOS 1:1 






FREEREC 0:1 






FREEBLK 0:10 






RSVBLK NULL: 10 




[1] 


RSVIX 0:10 
FPOOL NULL:50 




[2] 


DELTHR NULL:40 
DYN NULL: 25 






TOTAL LOGICAL RECORDS/DATA BLOCK: 


3 




FULL RECORDS/DATA BLOCK: 


2 




INITIAL ALLOCATED DATA BLOCKS: 


5 




INDEX ENTRY SIZE: 


44 




TOTAL ENTRIES/INDEX BLOCK: 


5 




FREE ENTRIES/PIXB: 


1 




RESERVE ENTRIE5/PIXB(BL0CKS): 


1 




FULL ENTRIES/PIXB: 


3 




RESERVE ENTRIES/SIXB: 


1 




FULL ENTRIES/SIXB: 


4 




DELETE THRESHOLD ENTRIES: 


2 




FREE POOL SIZE IN BLOCKS: 


29 




t OF INDEX BLOCKS AT LEVEL 1: 


2 




# OF INDEX BLOCKS AT LEVEL 2' 


1 




DATA SET SIZE IN EDX RECORDS: 


41 




INDEXED ACCESS METHOD RETURN CODE: 


-1 




SYSTEM RETURN CODE: 


-1 




CREATE/DEFINE FILE (Y/N)?: N 






ENTER COMMAND (?): 








[1] In this example there are still 5 total entries per index block. 
The 10 RSVIX parameter causes lOK X 5 (rounded up to 1) of the 
second-level index block (SIXB) entries to be reserved. 



In this case/ 1 reserve entry is allocated in the 
entries. Because the block pointed to by a SIXB i 
(PIXB)» blocks in the free pool are allocated for 
number of data blocks it can point to. Thus the t 
for these parameters is 1 (reserve entry) + 5 (tot 
(reserve block entries) = 8. Because only 50^ of 
free pool was requested/ 4 of the total free pool 
blocks specified on the DYN parameter for a total 
allocated to the free pool. 



SIXB leaving 4 full 
s also an index block 
the PIXB and the total 
otal free pool size 
al entries/PIXB) + 2 
the total possible 
blocks plus the 25 
of 29 blocks Mould be 
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o 



The total blocks allocated for this file is: 

Initial allocated data blocks 5 
Free blocks 2 

Free pool blocks 29 

Index blocks 3 

File control block + 2 

41 Total 

[2] The percentage (0-99) of blocks to retain in the cluster as records 
are deleted and blocks made available. This is knouin as the delete 
threshold (DELTHR). Mhen a block becomes empty » it is first determined 
if the block should be given up to the free pool by checking the 
response to this prompt. If the block is not given up to the free pool* 
it is retained in the cluster^ either as a free block or as an active 
empty block. The result of this calculation is rounded up so that any 
non-zero specification indicates at least one block. The calculation is 
adjusted to ensure that the cluster aluays contains at least one block. 
In this example^ the delete threshold Mas specified as 40%. This 
results in at least 2 blocks aluays being retained in each cluster. 

If the DELTHR parameter is specified as null (&) and DYN is not speci- 
fied* DELTHR defaults to the number of allocated blocks in the cluster 
plus one half of the value calculated by the FREEBLK prompt. 

If the DELTHR parameter is specified as null and a value is specified 
for the DYN parameter* DELTHR defaults to zero. 

Figure 3-8 on page 3-32 illustrates the format of the indexed file that 
Mould result from these SE command parameters. 
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Figure 3~8 . Indexed File Nith Reserved Index Entries 
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EXANPLE 5 - DEFINING A TOTALLY DYNAMIC FILE 

To define a totally dynamic file you need only supply the parameters 
Mhich describe the format of your records Mithin blocks' BLKSIZE^ 
RECSIZEy KEYSIZE. If the your keys do not begin in position 1 of your 
records* the KEYPOS parameter must be supplied. The DYN parameter must 
then be specified in the number of blocks to assign to the free pool. 

The folloMing display shous the use of the SE commands of the $IAMUT1 
utility to define a totally dynamic indexed file. Note that the result- 
ing file has only one allocated data block and one index block. The 
rest of the space is in the free pool as specified by the DYN parameter. 



o 



ENTER COMMAND (?): SE 




SET FILE DEFINITION PARAMETERS 




= EXIT 




1 = SIGNIFICANT PARAMETERS 




2 = ALL PARAMETERS 




3 = PARAMETERS FROM EXISTING INDEXED 


DATASET 


ENTER OPTION: 2 




SECONDARY INDEX (Y/N)?: N 




PARAMETER DEFAULT NEW VALUE 




BASEREC NULL 






BLKSIZE 


256 




RECSIZE 


70 




KEYSIZE 


40 




KEYPOS 1 






FREEREC 






FREEBLK 






RSVBLK NULL 






RSVIX 






FPOOL NULL 






DELTHR NULL 






DYN NULL 


:5300 




TOTAL LOGICAL RECORDS/BLOCK: 


3 


FULL RECORDS/DATA BLOCK-* 


3 


INITIAL ALLOCATED DATA BLOCKS: 


1 


INDEX ENTRY SIZE: 


14 


TOTAL ENTRIES/INDEX BLOCK: 


17 


FREE ENTRIES/PIXB: 





RESERVE ENTRIES/PIXB (BLOCKS): 





FULL ENTRIES/PIXB: 


17 


RESERVE ENTRIES/SIXB: 





FULL ENTRIES/SIXB: 


17 


DELETE THRESHOLD ENTRIES: 





FREE POOL SIZE IN BLOCKS: 


5300 


» OF INDEX BLOCKS AT LEVEL 1: 


1 


DATA SET SIZE IN EDX RECORDS: 


5304 


INDEXED ACCESS METHOD RETURN CODE: 


-1 


SYSTEM RETURN CODE: 


-1 


CREATE/DEFINE FILE (Y/N)?: N 




ENTER COMMAND (?): 





The total blocks allocated for this file is: 

Initial allocated data blocks 1 
Free blocks 

Free pool blocks 5300 

Index blocks 1 

File control block 2 

5304 Total 
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Figure 3-9 illustrates the format of the indexed file that Mould result 
from these SE command parameters. 











2 










Primary index 
block (PIXB) => 


3 






3 


Data 
block => 






Free 




4 5 




6 5303 




Free pool 
blocks => 
























































Figure 3-9. Totally Dynamic Indexed File 



o 
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DESIGNING INDEXED FILES USING $IAMUT1 - OPTION 3 

Option 3 alloMS you to define a neui file» using the same parameters that 
Mere used to create an existing file. Using this option you are not 
required to manually enter any parameters. You are prompted for the 
data set name and volume of the existing indexed file followed by the 
prompt "NEW PARAMETERS EXACTLY SAME AS ORIGINAL PARAMETERS (Y/N) ?". 
The effects of these two possibilities are described below*' 

Y The new file to be defined is to appear exactly like the existing 
file when it was created. In other words* the parameters to be used 
for defining the new file will be exactly like those of the existing 
file. 

An example of this situation is where you are satisfied with the 
structure of a currently existing file and now you want to build a 
similar file and you expect the same type of insert/delete activity. 

N The growth of the existing file is to be taken into account in defin- 
ing the new file. If the total number of records in the existing 
file do not exceed the number of base records when the file was 
defined^ the existing file parameters will be used without change to 
define the new file. However » if the number of records in the exist- 
ing file exceed the number of base records, the parameters for the 
new file will be adjusted as follows^ 

• BASEREC will be set as the current number of records in the 
exi sti ng file. 

• FPOOL will be set to null. 

• DYN will be set to the current number of free pool blocks in the 
exi sti ng f i le. 

• All other parameters will be the same as the corresponding exist- 
ing file parameters. 

Replying N to the prompt "NEW PARAMETERS EXACTLY SAME AS ORIGINAL 
PARAMETERS (Y/N)?", causes the file size to be adjusted to allow 
at least as many records to be loaded in the new file as appear 
in the existing file. This reduces the free pool amount based 
upon free pool depletion in the existing file. 

An example of this situation is where you wish to reorganize a file. 
The new file should be able to handle as many records as exist in the 
old file. 

Note: The parameters for a primary file must be set from another prima- 
ry file and parameters for a secondary file must be set from another 
secondary file. 



^h^ugljllr 
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flANUTl - OPTION 3 



The $IAMUT1 Indexed Access Method utility can be loaded Mith the Event 
Driven Executive operator command $L $IAHUT1. 

Uhen $IAMUT1 is loaded the first prompt displayed is as follouis! 



^ — V 

o 



tl3 ENTER COMMAND (?): SE 



[1] Entering SE causes the next prompt to be displayed. 



CZl 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATA SET 
ENTER OPTION: 3 



E2] Respond to this prompt by entering the digit '3' 
causes the folloMing prompts to be displayed. 



This response 



[33 



[5] 



SECONDARY INDEX (Y/N)?: N 

NAME OF EXISTING INDEXED DATASET (NAME, VOLUME) : EMPLFILE,EDX003 

NEW PARAMETERS EXACTLY SAME AS ORIGINAL PARAMETERS (Y/N)? Y 

DATA SET SIZE IN EDX RECORDS: 15 

INDEXED ACCESS METHOD RETURN CODE: -i 

SYSTEM RETURN CODE: -1 

CREATE/DEFINE FILE (Y/N)?: N 



o 



E3] Enter the name of the data set and volume whose values you wish this 
data set to copy. 

[4] If all of the parameter values used to define the existing file ini- 
tially are satisfactory, reply Y. However, if you want to change any of 
the parameters, based on current file status, or you want to reorganize 
the existing file, reply N. Replying N will cause the parameter values 
for BASEREC and FPOOL to be adjusted so that you can load as many 
records into the new file as &ri& now contained in the existing file. 

[53 If you have verified that the parameters you entered are correct, 
the data set (file) size in EDX records is acceptable, and the return 
codes Br^ both -1, you can reply Y and the file can be defined and cre- 
ated. If you wish to change any of the parameters, reply N and you can 
reenter the SE command and enter any new values for the parameters. 
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DEFINING, CREATING. AND LOADING A FILE - SUHMARY 

This chapter has presented the structure, content and principles of pri- 
mary index files. Several examples have been used to shoM Mhat results 
given parameter values have when defining a primary index file. 

In those examples the SE command of $IAMUT1 Mas used extensively. In 
replying to the SE prompt "DEFINE/CREATE FILE (Y/N)?:", N was used in 
this chapter. This allows you to reenter the SE command and go through 
the prompt sequence again, changing any parameter values as required. 

To see the result of replying Y, see the example used in Chapter 
Z, "Using the Indexed Access Method" on page 2-1. Uhen you reply Y to 
the DEFINE/CREATE prompt, you enter the function called defining the 
file. You can enter the define file directly anytime that $IAMUT1 is 
loaded by responding with DF to the prompt "ENTER COMMAND (?):." Using 
the DF (define file) command is described in detail under "DF — Define 
Indexed File" on page 9-6. 

When you reply Y to the prompt, "INVOKE LOAD(L), REORGANIZE(R) OR END(E) 
AFTER CURRENT FUNCTION ?:", you are given the opportunity to enter the 
$IAMUT1 functions of load, reorganize, or end. blhile in the SE 
function, load, reorganize, and end can be entered by replying with the 
letters L, R, or E, respectively. However, these functions can be 
entered directly from the prompt "ENTER COMMAND (?):" with LO for load, 
RO for reorganize, or EN for end. 

Using the LO (load) command is described in detail under "LO — Load 
Indexed File" on page 9-22. 

Using the RO (reorganize) command is described in detail under 
"RO — Reorganize Indexed File" on page 9-30. 

Entering EN (end) terminates the current session of the SE command of 
$IAMUT1. Entering EN to the prompt "ENTER COMMAND (?):" will then ter- 
minate the $IAMUT1 utility. 
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CHAPTER <^. LOADING THE PRIHARY INDEX FILE 

This section describes the process and methods of loading a file. 
You can use tMo methods to load base records: 

1. The $IAMUT1 utility 

2. An application program. 

The methods are described in the following sections. 



LOADING THE PRIMARY INDEX FILE 

The Indexed Access Method uses tMo modes to place records into an 
indexed file: 

1. Load mode: records are loaded sequentially in ascending order by 
key, skipping any free space. The records loaded are called base 
records. Each record loaded must have a key higher than any key 
already in the file. 

2. Process mode: records are inserted in their proper key position 
relative to records already in the file. Records are inserted using 
the free space that Mas skipped during loading or» if a record has a 
neM high key> it is placed in a base record after the last loaded 
record. If no base records are available* it is placed in the free 
space after the last loaded record. 

The total number of base records that can be loaded is established Mhen 
the indexed file is defined by the $IAMUT1 utility. It is not necessary* 
houiever* to load all (or any) base records before processing can begin. 
The file can be opened for loading some of the base records* closed and 
then reopened for processing (including inserts)* and later opened for 
loading more base records. Figure 4-1 on page 4-2 illustrates this 
sequence. 

Note: Programs written in COBOL are an exception to this; COBOL pro- 
grams can use load mode only once for any given indexed file. 
Therefore* all base records loaded in load mode must be loaded together. 
Base records loaded later must be inserted in process mode (with slower 
performance) . 
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LOAD MODE 
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after step 1 
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PROCESS MODE 
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-High key after 
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Figure 4-1. Loading and Inserting Records 

The amount of free space for inserts (if any) is specified using the 
$IAMUT1 utility uihen the indexed file is built. This free space can be 
distributed throughout the file in the form of free records within each 
data block> free blocks within each cluster, and in a free pool at the 
end of the file. 
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LOADING BASE RECORDS USING $IAMUT1 

After the indexed file has been defined by the $IAMUT1 DF command, you 
can load base records from a sequential file into the indexed file. 
Loading the file can be done directly by responding Y to the prompt "IN- 
VOKE LOAD(L), REORGANIZE(R) OR EMD(E) AFTER CURRENT FUNCTION?", when 
defining the file, or by using the LO command after the file has been 
defined. The data in the sequential file must be in ascending order by 
key. 

To load base records using $IAMUT1, do the following: 

1. Prepare a sequential file for input to the indexed file 

2. Load the sequential file into the indexed file. 



Preparing Input for the indexed File 

Select one of the following methods to prepare the input in a sequential 
file to be loaded into an indexed file: 

• If your data records are 72 bytes or less, use one of the text edi- 
tors to enter your data or one of the communications utilities to 
get the data into an Event Driven Executive sequential file. In 
either case, you must know the record format used by the utility. 
The utilities put two 80-byte records in each 256-byte Event Driven 
Executive record. The first record begins at location 1, and the 
second record begins at location 129. This results in a blocked 
sequential file which can be used to load the indexed file when 
using the LO command of $IAMUT1. (A detailed description of the LO 
command is under "LO — Load Indexed File" on page 9-22.) Specify 128 
for the input record length and 256 for the input block size. 

• If your records have more than 72 bytes of data, you must create a 
program that accepts the data records and writes them to a disk, 
diskette, or magnetic tape file. 

The data must be in ascending order, based upon the field you use as the 
key. 
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Loading an indexed File from a Sequential File 



The procedure for loading an indexed file from a sequential file is: 

1. Invoke $IAMUT1 using the system command $L. 

2. If you ixiant a hard copy of the terminal prompts and responses^ enter 
an EC command. Respond to the prompt with a Y. This will print all 
further prompts and responses of $IAMUT1 on the $SYSPRTR device and 
your terminal. If a hard copy is not required* omit this step. 

3. Enter the LO command. 

Respond to the following prompts with your data set information. 



ENTER COMMAND (?): LO 

LOAD ACTIVE 

ENTER OUTPUT DATASET (NAME, VOLUME) : 

$FSEDIT FILE RECSIZE = 128 

INPUT RECORD ASSUMED TO BE 80 BYTES. OK? 

ENTER INPUT BLOCKSIZE (NULL = UNBLOCKED): 

ENTER INPUT DATASET (NAME, VOLUME) : 

LOAD IN PROCESS 

END OF INPUT DATASET 

ANY MORE DATA TO BE LOADED?: N 

6 RECORDS LOADED 
LOAD SUCCESSFUL 



Enter the EN command to end $IAMUT1. Your program is now loaded and 
you can process the data with your application program. 
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LOADING BASE RECORDS FROM AN APPLICATION PROGRAM 

Base records are records placed into an indexed file in ascending neui 
high key sequence. That is, if a record added to the file has a key 
higher than any other record in the file* it is placed in a base record 
slot. Base records are placed in the base record slots reserved for 
them by use of the BASEREC parameter. You can use either the $IAMUT1 LO 
command or an application program to load the base records. 

Base records must be loaded in ascending order by key. If you are writ- 
ing your ouin program to load the f i le» use a LOAD request to connect the 
file to load base records. Then issue a PUT for each record. Uhen the 
desired records have been loaded* issue a DISCONN request to terminate 
the load procedure. The only requests that can follow a LOAD request 
are: PUT, EXTRACT, and DISCONN. 

You can also insert base records in process mode by using a PROCESS 
request to connect the file, followed by a PUT request for each record 
to be loaded. Loading records in process mode with an application pro- 
gram is discouraged because of slower performance. 

Unless the base record loading program is written in COBOL, it need not 
load all base records at one time. A file that already contains records 
can be reconnected to load more records, but the key of each new record 
must be higher than any key already in the file. 

COBOL programs must either load all the base records in load mode at 
once (because only one use of load mode is allowed on a given file) or 
insert the records in process mode as needed. 

The limit on base records as specified on the SE command of the Indexed 
Access Method utility program ($IAF1UT1) cannot be exceeded. If you 
attempt to load a record after the last allocated record area has been 
filled, an end-of-file condition occurs. 



LOADING BASE RECORDS FRON A SEQUENTIAL FILE IN RANDOH ORDER 

In order to load base records from a sequential file where keys are in 
random order, code an EDL program to open the indexed file in load mode. 
Load the SORT/MERGE program with an output exit routine specified. 
Write (PUT) each record to the indexed file as it is received in the 
output exit routine from SORT/MERGE. The output exit routine can also 
screen out duplicates or other unwanted records. For information on 
using the SORT/MERGE Program Product, refer to IBM Series/l Event Driven 
Executive Sort/Merge Programmer's Guide , SL23-0016. 
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CHAPTER 5. BUILDING A SECONDARY INDEX 



Indexed files* like most data record files* can be a common base for 
many applications. You can assign secondary keys in your indexed files 
for greater flexibility in accessing records in indexed files. 

Secondary keys are accessed through a secondary index (a separate file). 
Your application program requests records by their secondary key and 
secondary index file name. The secondary index is used to retrieve the 
record by its secondary key from the primary index file. 

You can have more than one secondary index for a given primary index 
file. In order for the Indexed Access Method to knoui the relationships 
betuieen secondary indexes and primary index files, you must create and 
maintain a directory with that information. 



SECONDARY KEYS 



^*\^ 



Secondary keys are not required to be unique; different records in an 
indexed file can have the same key values in their secondary key field. 

The secondary key can be any field within your data record that you 
select* however* it must meet the following requi rements^ 

• The selected field must start at the same location in each record. 

• All portions of the key field must be contiguous. 

• The secondary key length cannot exceed 250 bytes. 

In a secondary index* the Indexed Access Method assigns a sequence num- 
ber to each secondary key. The sequence number shows the sequence of 
loading or inserting secondary index entries. 

A sample layout of a secondary index record follows^ 



Secondary Sequence Primary 
Key Number Key 



Relative 

Block 

Number 



SMITH 


0001 


IZS'iSAB 


RBN 
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THE DIRECTORY 

In order for the Indexed Access Method to know the relationships between (I J 
secondary indexes and primary index files, you must create and maintain ^k^ 

a di rectory with that information. The directory describes all indexed 
files in the system which aret either secondary indexes, or primaries 
which have secondary indexes associated with them. Primary index files 
which do not have secondary indexes associated with them &r& not in the 
directory. Use the $IAMUT1 utility to create and maintain the 
di rectory. 

The directory name is $IAMDIR and it resides on the IPL volume. 

The directory contains one or more groups of entries. Each group begins 
with an entry for the primary file and is followed by an entry for each 
secondary index which references that primary file. 

You have the responsibility of maintaining the directory using the 
$IAMUT1 utility. 

Each entry in the directory contains the following information^ 

File name 

Volume name 

Primary file or secondary index indicator 

Independent indicator 

Invalid index indicator (secondary entry only) 

Automatic update indicator (secondary entry only). 

FILE NAME: The file name is the data set name supplied when the primary ziT x 

index file or secondary index entry is inserted in the directory, (^ 



VOLUME NAME*' The file location is the volume label name where the index 
resides that this entry is for. 

INDEPENDENT PROCESSING INDICATOR: Each entry in the directory contains 
an independent indicator. Independent means that the file is to be 
treated as an independent file without regard to associated primary or 
secondary files. If the independent indicator is set on for a file that 
is explicitly opened, the automatic update indicator is ignored. 

In the case of a secondary index, this means that records retrieved are 
internal secondary index records, not data records from the primary 
file. In addition, independent means that any modification to the file 
(either primary or secondary) will not be reflected in its associated 
files. Also any changes made in a secondary index will not be reflected 
in the associated primary or other secondary index files. 

In the case of a primary entry, any modification to the primary file 
will not be reflected in the associated secondary index files. 



'<.J 
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INVALID INDICATOR: The invalid indicator is initially turned on in the 
directory* by the directory function of $IAMUT1» uihen the secondary 
entry is inserted in the directory. 

A secondary index entry is marked invalid until the secondary index has 
been loaded. 

The load function of the utility turns off the invalid indicator. 

If you build the secondary index with an application program* you must 
also turn off the indicator. The UE subcommand of the DR function in 
$IAMUT1 is used to turn off the invalid indicator* after you have suc- 
cessfully loaded your secondary index. 

AUTOMATIC UPDATE INDICATOR: Each secondary index entry in the directory 
contains an automatic update indicator. Any modification to the primary 
file (either directly or through any secondary index activity) results 
in an automatic update to all secondary indexes Mhose automatic update 
indicator in the directory Mas specified Mith Y. Thus* a secondary 
index flagged as auto-update can be thought of as "dynamic." Each sec- 
ondary index remains open until all users of it have closed. However* 
if the independent indicator is set on for a file that is explicitly 
opened* the automatic update indicator is ignored. 

If the automatic update indicator Mas specified as N* changes are not 
reflected in that secondary index. This Mould be a "static" index. The 
assumption is that a static index Mould be rebuilt periodically to bring 
it up to date. 



ALLOCATING AND INSERTING ENTRIES IN A DIRECTORY 

Although the Indexed Access Method references the directory* it never 
modifies the directory. The one function that is performed on the 
directory automatically is that the secondary load option sets the 
invalid indicator off folloMing successful completion. 

To define the existence of a secondary index* use $IAMUT1 to perform the 
folloMing two steps: 

1. Allocate a directory using the DR (directory function) of $IAMUT1 

2. Establish the fact that a secondary index Mill exist by making an 
entry in the directory using the IE (insert entry) command of 
$IAMUT1. 

Remember that primary index file entries precede their associated sec- 
ondary index entries. The $IAMUT1 Indexed Access Method utility can be 
loaded Mith the Event Driven Executive operator command $L $IANUTI. 
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Uhen $IAMUT1 is loaded^ the first prompt displayed is as folloMS^ 



[1] 



ENTER COMMAND (?): DR 



[13 Entering DR causes the folloMing prompt sequence. 



[23 
[33 
C43 

[53 



ENTER DIRECTORY COMMAND (?): AL 

MAX t OF DIRECTORY ENTRIES*. 10 

THE DIRECTORY DS REQUIRES 1 EDX RECORDS, CONTINUE (Y|N|EN)? Y 

DIRECTORY DATA SET ALLOCATED: $IAMDIR, EDX002 



[23 Responding to this prompt Mith AL (allocate) causes a directory 
allocation sequence to begin. 

Note: The allocation sequence is only required the first time you set 
up secondary indexes. Future entries can be added using (IE) insert 
directory function. 

[33 Reply Mith maximum number of directory entries you Mant allocated 
for the directory. You will need one entry for each secondary index and 
one entry for each primary that has a secondary index associated with 
it. A null response will allocate the maximum (default) of 47 entries. 

[43 Based on your previous response, the size of the required directory 
is calculated and you are informed of the number of EDX records required 
to allocate your requested directory. You &re also given three options 
as follows: 

1. Y - the opportunity to continue the directory allocation 

2. N - do not allocate the directory; allow me to change the size of 
the directory 

3. EN - end the allocate function; return to C13 of the DR function of 
$IAMUT1 to enter another command. 

[53 Because CYl was replied, the directory is allocated. If the direc- 
tory is allocated successfully, you are informed that it has been allo- 
cated, the name of the directory of course is $IAMDIR, and the IPL 
volume where it is always allocated is displayed. 

Note: The allocation sequence is only required the first time you set 
up secondary indexes. 
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The prompt sequence continues. 



CI 



[6] 

[73 
[81 

[91 

UO] 



ENTER DIRECTORY COMMAND (?): IE 

(DSNAME, VOLUME): EMP«,EDX002 

IS THIS A SECONDARY ENTRY (Y/N) N 

DIRECTORY INSERT SUCCESSFUL 

ENTER DIRECTORY COMMAND (?): IE 






C6] Replying IE (insert entry) alloMS you to insert entries into the 
directory. A primary entry must be inserted before its associated sec- 
ondary index entries. 

Note: Primary files may exist at this time» hoMever» secondary indexes 
cannot be created until an entry for it has been inserted in the direc- 
tory. 

171 Your data set name and volume name uihere your primary index file or 
secondary index resides. The volume name is not required if the data 
set is on system volume such as EDX002. 

[8] This prompt lets $IAMUT1 know whether to set the primary or second- 
ary entry indicator. Reply Y for a secondary index entry* or N for a 
primary index entry. 

[9] This message informs you that the entry has been successfully 
inserted into the directory. 

[10] At this point you can end the directory function by responding to 
the prompt with EN, or reply any other directory function. 

Because this was a primary entry we can now respond with IE and insert 
secondary directory entries. In this case, secondary entries are being 
made and that is why we responded with IE and caused the prompts to con- 
tinue as follows: 



[11] 
[12] 

[13] 
[14] 

[15] 

[16] 



(DSNAME, VOLUME): NAME,EDX002 

IS THIS A SECONDARY ENTRY (Y/N)? Y 

ASSOCIATED PRIMARY ENTRY (DSNAME, VOLUME) : EMP«,EDX002 
AUTO-UPDATE (Y/N)? Y 

DIRECTORY INSERT SUCCESSFUL 

ENTER DIRECTORY COMMAND (?): IE 



[11] The secondary index data set name is NAME on volume EDX002 and 
therefore, the volume name could have been omitted. 

[12] Because this is an entry for a secondary index, the correct reply 
is Y. At this point in the prompt sequence the prompts change from the 
previous sequence because of the positive reply, Y. 

[13] The associated primary entry data set name, which the previous 
entry sequence (5 - 9) was for, is EMP9fEDX002. This is the point where 
the secondary indexes establish their association to the primary index 
files for which the secondary index is built. 

[14] The response to this prompt establishes whether automatic update 
option is to be effective for this secondary index. For a description 
of automatic update, see "Automatic Update Indicator" on page 5-3. The 
recommended response is Y, also if a null entry is supplied, the default 
i s Y (yes) . 
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[15] You are informed Mhen the insert is successfully completed. 

C16] As seen previously^ you again have the option of selecting another 
directory function. In this description^ IE Mas again selected to 
insert the following two secondary index entries. 

A second secondary index entry named CITY>EDX002» is inserted for the 
associated primary index file named EMP#. 



o 



(DSNAME, VOLUME): CITY,EDX002 

IS THIS A SECONDARY ENTRY (Y/N) Y 

ASSOCIATED PRIMARY ENTRY (DSNAME, VOLUME) : EMP»,EDX002 
AUTO-UPDATE (Y/N)? Y 



DIRECTORY INSERT SUCCESSFUL 
ENTER DIRECTORY COMMAND (?): 



IE 



A third secondary index entry named LEVEL > EDX002» is inserted for the 
associated primary index file named EMPf. 



(DSNAME, VOLUME): LEVEL, EDX002 

IS THIS A SECONDARY ENTRY (Y/N) Y 

ASSOCIATED PRIMARY ENTRY (DSNAME, VOLUME) : EMP«,EDX002 
AUTO-UPDATE (Y/N)? N 

DIRECTORY INSERT SUCCESSFUL 



( 



.Jr 



The following example uses a different directory function? LE (list 
directory entries). This example shows the directory which was just 
allocated and four entries inserted; one primary and three secondaries, 



[1] 


ENTER DIRECTORY COMMAND (?): LE 






[2] 


ENTRY (DSNAME, VOLUME) BLANK=ALL: 






[3] 


PRIMARY INDE- 
DSNAME VOLUME DATA SET PENDENT 


INVALID 


AUTO 
UPDATE 


[41 
[51 
[63 
t7] 


EMP# EDX002 YES NO 
NAME EDX002 NO NO 
CITY EDX002 NO NO 
LEVEL EDX002 NO NO 


YES 
YES 
YES 


xxxx 
YES 
YES 
NO 


[81 
[9] 


NUMBER OF DIRECTORY ENTRIES USED 
NUMBER OF AVAILABLE ENTRY SLOTS = 
DIRECTORY LIST COMPLETED 


= 4 
6 
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[1] The DR (directory) subcommand LE prints specified directory statis- 
ti cs. 

[23 Respond to this prompt Mith the specific data set name and volume 
you Nish the statistics listed for, or press the Enter key with no 
DSNAME or VOLUME name specified to list the entire directory. This 
request is for all entries in the directory which was just allocated and 
inserts made in the previous examples. 

[31 Column headings for the listed information from the directory show- 
ing the following information: 

• Data set name that the statistics are for 

• Volume name where the data set resides 

• Whether this is a primary or secondary index 

• Is the independent indicator on for the named data set (yes or no) 

• Is the invalid index indicator on for the named data set (yes or no) 

• Is the auto-update indicator on for the named data set (yes or no). 

C41 For the primary index file (data set) named EMPt» on volume EDX002y 
the independent indicator is off, there is no invalid indicator for a 
primary file, there is no auto-update indicator for a primary file. 
Modifications are always made to the primary index file if the independ- 
ent indicator is not on. 

[51 For the secondary index named NAME, on volume EDX002, the independ- 
ent indicator is off, the invalid index indicator is on because the 
index has not been loaded, the auto-update indicator is on as requested 
when the entry for this secondary index was inserted. 

[63 Same statistics as previous data set. 

t71 For the secondary index named LEVEL, on volume EDX002, the inde- 
pendent indicator is off, the invalid indicator is on (index is not 
loaded), and the auto-update indicator is off. 

[8] There were 10 entries allocated and ^ inserts (one primary and 
three secondaries). 

19] The resulting empty directory slots for additional inserts is six. 



SECONDARY INDEX 



Depending upon your need, you may have one or several secondary indexes 
for a given primary index file. A secondary index is built for a spe- 
cific primary index file and cannot be used with any other file. Each 
secondary index is a separate Indexed Access Method file. 

Application programs accessing indexed records by their secondary key 
are required to open the secondary index and access the records using 
the secondary key. When primary index records are updated, inserted or 
deleted, some or all secondary indexes associated with that primary 
index file can be updated automatically by the Indexed Access Method, 
according to the options selected when the secondary index directory is 
set up. 
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Setting up a Secondary Index 

To provide access by a secondary key» you must build a secondary index. 
The secondary index must have a unique file name. 

To set up a secondary index> you must do the following using ^lAMUTl: 

1. Create the secondary index 

2. Load the secondary index. 



DEFINING AND LOADING A SECONDARY INDEX 

Your secondary index should be structured so that the base records 
parameter is equal to or greater than the number of records in the pri- 
mary index file. This will assure that when you build your secondary 
indexy it will be large enough to hold at least as many records as there 
are in the primary index file. 

Note: If the associated primary index file» for which the secondary is 
being defined^ is an existing Version 1 created file, you must use $VER- 
IFY to update the record counts before defining the secondary file. 

The key size and key position specified for the secondary index must be 
the key size and starting position of the secondary key within the pri- 
mary index record. 

You can create a secondary index the same way you create a primary index 
file, using the $IAMUT1 utility SE (and DF) commands. The utility 
prompts you requesting whether the secondary index being defined is also 
to be loaded. If YES is specified, the utility does the following^ 

1. Creates the secondary index but does not format it 

2. Opens the primary file, reads the records sequentially, and extracts 
the primary and secondary keys from each record, retaining the rela- 
tive data block address (RBN) of each record 

3. Invokes the Sort/Merge Program Product to sort by secondary key (and 
by primary key within secondary) 

4. Opens the secondary index, formats the sorted keys, their sequence 
numbers which are now assigned, and the relative data block 
addresses of the primary file data records into blocks 

5. Mrites the blocks into the secondary index. 

Before a secondary index can be loaded, it must have been defined using 
$IAMUT1. A secondary index can be deleted, then created and loaded 
again at any time. If a primary file has more than one secondary index, 
each must be created and loaded separately. 



o 
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IZANUTI option Stltction Guide 



Having read the preceding material* you are probably ready to make a 
choice as to Mhich option you want to use in defining your secondary 
index. The folloNing table Mill help you to find the appropriate infor- 
mation» based on your secondary index defining objectives. 



Your objective 


Option 


Information location 


You Nant the Indexed Access 
Method to calculate and 
structure your index 


Option 1 


See "Option 1" on page 5-10 


You Mant to structure your 
secondary index using specif- 
ic parameters 


Option 2 


See "Option 2" on page 5-12 


You uant to structure your 
secondary index using the 
parameters of an existing 
secondary index 


Option 3 


See "Option 3" on page 5-1^ 
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EXAMPLE l; DEFINING A SECONDARY INDEX USING tlAHUTl 

The Indexed Access Method utility* $IAMUT1> option 1» provides you with 
the opportunity to select only those parameters necessary to set up a 
secondary index. 



OPTION 1 

The $IAnUTl Indexed Access Method utility can be loaded with the Event 
Driven Executive operator command $L $IAMUT1. 

Mhen $IAMUT1 is loaded the first prompt displayed is as folloMS* 



ill 



ENTER COMMAND (?): SE 



[1] Entering SE causes the following option list prompt to be displayed. 



C2] 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATA SET 
ENTER OPTION: 1 



[2] Respond to this prompt by entering the digit *1*. This response 
causes a one line prompt from the next prompt sequence to be displayed. 
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Note: Although the folloMing prompts are displayed one line at a time 
Mhen using the utility^ all the prompts are listed here in logical 
groups for simplicity in describing the parameters. 



[33 

[5] 
[63 



t73 
[8] 



SECONDARY INDEX (Y/N)?: Y 

ENTER SECONDARY DATASET (NAME, VOLUME) : 

SECONDARY KEY SIZE -^ 

SECONDARY KEY POSITION :5 



CITY,EDX002 



DATA SET SIZE IN EDX RECORDS: 

INDEXED ACCESS METHOD RETURN CODE: 

SYSTEM RETURN CODE: 

CREATE/DEFINE FILE CY/N)?: Y 

DYNAMIC DATA SET EXTENTS ON FILE (Y/N): N 

DO YOU WANT IMMEDIATE WRITE-BACK? N 

INVOKE LOAD(L), REORGANIZE(R) OR END(E) AFTER CURRENT FUNCTION? L 

DEFINE IN PROGRESS 

DATA SET SIZE IN EDX RECORDS: 

INDEXED ACCESS METHOD RETURN CODE: 

SYSTEM RETURN CODE: 

PROCEED WITH LOAD/REORGANIZE (Y/N)? Y 

SECONDARY INDEX LOAD ACTIVE 

ANSWER NULL FOR ALLOCATING DEFAULT WORK DATASET $SORTWRK 

SORT WORK DATASET (DSNAME, VOLUME) : 

SORT WORK DATASET REQUIRES 20 EDX RECORDS 

5 RECORDS LOADED 
SECONDARY LOAD SUCCESSFUL 



10 
-1 
-1 



10 
-1 
-1 



[33 Reply Y to this prompt because you are defining a secondary index. 

E43 Enter the data set name and volume Mhere this index is being 
defined. 

[53 Specify the length of the secondary key within the primary index 
record for which this index is being defined. 

t63 Specify the starting position of the secondary key within the prima- 
ry index file record. The first byte of the record is number 1. 

[73 The secondary index load function is active. 

[83 At this point there are four possible responses: 

1. A load error may occur while trying to load $SORT due to a lack of 
sufficient main storage in the partition. If this happens, you can 
either change to another partition or end one or more programs in 
the current partition. However, do not cancel $IAM. 

2. A null response, just pressing the enter key, will cause $SORTWRK to 
be allocated on the IPL volume if space is available. The size of 
the data set is calculated by the utility. If $SORTWRK already 
exists, this indicates that another user is using the default work 
data set and you will be prompted again for a work data set name. 

3. Entering a comma (,) followed immediately with a volume name, then 
pressing the enter key, causes the utility to try to allocate 
$SORTWRK on the specified volume. 

^. Entering a data set name and optionally a volume name (no volume 

name entered causes the IPL volume to be used) causes the utility to 
calculate the size of data set required and allocate it according to 
your response. 
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Notes: 



If $IAMUT1 allocates the data set for yoUf the data set Mill be 
automatically deleted at the end of the sort operation. HoMever, if 
you provide either the name of an already existing data set (other 
than $SORTURK) or a data set name you uant $IAMUT1 to allocate, the 
data set will not be deleted at the end of the sort. 

The sort Mork data set cannot always be calculated precisely because 
the size is dependent on several variables related to the input 
file. In most cases the calculated size will be adequate. However, 
if the size calculated is too small, the sort will end prematurely. 
If this happens you can preallocate a data set with a larger size 
than that calculated by $IAMUT1 and execute the sort again. 



o 



OPTION 2 



The $IAMUT1 Indexed Access Method utility can be loaded with the Event 
Driven Executive operator command $L $IAHUT1. 

When $IAf1UTl is loaded the first prompt displayed is as follows^ 



[11 




[13 Entering SE causes the following option list prompt to be displayed 



E2] 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATA SET 
ENTER OPTION: 2 



,€" 



y 



E2] Respond to this prompt by entering the digit *2'. This response 
causes a one line prompt from the next prompt sequence to be displays* 

Note: Although the following prompts are displayed one line at a 
time when using the utility, the entire prompt list is shown for 
simplicity in presentation. 



o 



5-12 SC34-0771 






[3] 


SECONDARY INDEX (Y/N)?: Y 








[4] 


ENTER SECONDARY DATASET (NAME, VOLUME) : 


NANE,EDX002 




[51 


PARAMETER DEFAULT NEW VALUE 










BASEREC 20 


20 










BLKSIZE 256 












KEYSIZE 4 












KEYPOS 5 












FREEREC 












FREEBLK 












RSVBLK NULL 












RSVIX 












FPOOL NULL 












DELTHR NULL 












DYN NULL 


05 










TOTAL LOGICAL RECORDS/DATA BLOCK: 




15 






FULL RECORDS/DATA BLOCK: 




15 






INITIAL ALLOCATED DATA BLOCKS: 




2 






INDEX ENTRY SIZE: 




12 






TOTAL ENTRIES/INDEX BLOCK: 




20 






FREE ENTRIES/PIXB: 











RESERVE ENTRIES/PIXB(BLOCKS): 











FULL ENTRIES/PIXB: 




20 






RESERVE ENTRIES/SIXB: 











FULL ENTRIES/SIXB: 




20 






DELETE THRESHOLD ENTRIES 











FREE POOL SIZE IN BLOCKS 




5 






t OF INDEX BLOCKS AT LEVEL 1: 




1 






DATA SET SIZE IN EDX RECORDS: 




10 






INDEXED ACCESS METHOD RETURN CODE: 




-1 






SYSTEM RETURN CODE: 




-1 






CREATE/DEFINE FILE (Y/N)?: y 










DYNAMIC DATA SET EXTENTS ON FILE? 


(Y/N) 


: N 






DATA SET ALREADY EXISTS 










DELETE AND REALLOCATE (Y/N): Y 










DELETE AND REALLOCATE COMPLETED 










DO YOU WANT IMMEDIATE WRITE-BACK? 


N 








INVOKE LOAD(L), REORGANIZE(R) OR END(E) 


AFTER CURRENT FUNCTION? 


L 




DEFINE IN PROGRESS 










DATA SET SIZE IN EDX RECORDS: 




10 






INDEXED ACCESS METHOD RETURN CODE: 




-1 






SYSTEM RETURN CODE: 




-1 






PROCEED WITH LOAD/REORGANIZE (Y/N) 


? Y 






[6] 


SECONDARY INDEX LOAD ACTIVE 










ANSWER NULL FOR ALLOCATING DEFAULT 


WORK 


DATASET $SORTWRK 




[73 


SORT WORK DATASET (DSNAME, VOLUME) : 










SORT WORK DATASET REQUIRES 20 


EDX 


RECORDS 






5 RECORDS LOADED 










SECONDARY LOAD SUCCESSFUL 









[31 Reply Y to this prompt because you are defining a secondary index. 

[41 Enter the data set name and volume uhere this index is being 
def i ned. 

[51 The folloMing parameter list allows you to precisely define the sec- 
ondary index structure. 

[63 The secondary index load function is active. 

[73 If the name of a data set and volume are entered, Sort/Merge Mill 
use it for the Mork data set. If a null response is made, the utility 
Mill calculate the size data set required and allocate it Mith the name 
$SORTWRK on the IPL volume. 
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Notes: 



For a more complete description of the responses available and the 
possible conditions that could exists see step 8 description under 
"Option 1." 

The following messages are from the IBM Sort/Merge Program Product, 
program number 5719-5M2. The following message list is the result 
of the secondary load function calling and executing Sort/Merge. 
For a description of the Sort/Merge program and its messages refer 
to IBM Series/1 Event Driven Executive Sort/Merge Programmer's 
Guide , SL23-0016. 



SORT099N + 1 + 2 + 3 + 4 + 

SORTOOOX LO$SYSPRTR 

SORTOOIP SORT/MERGE SPECIFICATION PHASE STARTED 

SORTOOOX HSORTR 12A0DP 

SORTOOOX DW $SORTWRKTVOL 

SORTOOOX FNCOOOl 12 

SORTOOOX FR 

SORT075P SPECIFICATION PHASE ENDED 

SORT076P INPUT PHASE STARTED 

SORT082P INPUT PHASE ENDED 5 1 

SORT085P FINAL MERGE PHASE STARTED 1 4 

SORT086P FINAL MERGE PHASE ENDED 

SORT088P RECORDS READ FROM INPUT DATA SETCS): 

SORT089N RECORDS INSERTED BY INPUT EXIT ROUTINE: 

SORT090N RECORDS DELETED BY INPUT EXIT ROUTINE: 

SORT091N RECORDS INSERTED BY OUTPUT EXIT ROUTINE: 

SORT092N RECORDS DELETED BY OUTPUT EXIT ROUTINE: 

SORT093N RECORDS WRITTEN TO OUTPUT DATA SET: 

SORT094N I/O ERRORS ACCEPTED: 

SORT095N I/O ERRORS SKIPPED: 

S0RT1^9N RECORDS SORTED OR MERGED: 

S0RT097P NORMAL ENDING FOR SORT/MERGE PROCESSING 






/if A 



OPTION 3 



The $IAMUT1 Indexed Access Method utility can be loaded with the Event 
Driven Executive operator command $L $IAMUT1. 

Uhen $IAMUT1 is loaded the first prompt displayed is as follows: 



[13 



ENTER COMMAND (?): SE 



CI] Entering SE causes the following option list prompt to be displayed, 



C2] 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATA SET 
ENTER OPTION: 3 



^IbbJ^ 
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[2] Respond to this prompt by entering the digit '3'. This response 
causes a one line prompt from the next prompt sequence to be displayed. 

Note: Although the follouiing prompts are displayed one line at a time 
when using the utility* the entire prompt list is shown for simplicity 
in describing the parameters. 



[33 

[5] 
[63 



t73 



SECONDARY INDEX (Y/N)?'- Y 

ENTER SECONDARY DATASET (NAME, VOLUME) : LEVEL, EDX002 

NAME OF EXISTING INDEXED DATA SET (NAME, VOLUME) : CITY,EDX002 

NEW PARAMETERS EXACTLY SAME AS ORIGINAL PARAMETERS (Y/N)? Y 

DATA SET SIZE IN EDX RECORDS: 10 

INDEXED ACCESS METHOD RETURN CODE: -i 

SYSTEM RETURN CODE: -i 

CREATE/DEFINE FILE (Y/N)?: y 

DYNAMIC DATA SET EXTENTS ON FILE (Y/N): N 

NEW DATASET IS ALLOCATED 

DO YOU WANT IMMEDIATE WRITE-BACK? Y 

INVOKE LOAD(L), REORGANIZE(R) OR END(E) AFTER CURRENT FUNCTION? L 

DEFINE IN PROGRESS 

DATA SET SIZE IN EDX RECORDS: 10 

INDEXED ACCESS METHOD RETURN CODE: -i 

SYSTEM RETURN CODE: -1 

PROCEED WITH LOAD/REORGANIZE (Y/N)? Y 

SECONDARY INDEX LOAD ACTIVE 

ANSWER NULL FOR ALLOCATING DEFAULT WORK DATASET $SORTWRK 

SORT WORK DATASET (DSNAME, VOLUME) : 

SORT WORK DATASET REQUIRES 20 RECORDS 

5 RECORDS LOADED 
SECONDARY LOAD SUCCESSFUL 






[3] Reply Y to this prompt because you are defining a secondary index. 

t4] Enter the data set name and volume where this index is being 
def i ned. 

[5] Enter the data set name and volume of the secondary index whose 
parameters are to be used for this index. 

[61 If all parameters are to be the same as those initially set for the 
data set name entered in prompt [33, reply Y. However, if you want the 
parameters adjusted, based on current file status, reply N. 

C73 If the name of a data set and volume are entered, Sort/Merge will 
use it for the work data set. If a null response is made, the utility 
will calculate the size data set required and allocate it with the name 
$SORTWRK on the IPL volume. 

Note: For a more complete description of the responses available and 
the possible conditions that could exist, see step 8 description under 
"Option 1." 
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LOADING A SECONDARY FILE WITH AN APPLICATION PROGRAM 

You have the option of alloMing $IAMUT1 to load your secondary file at 
the time it is created/ as was demonstrated in "Option 2" on page 5-12» 
or you can load it with an application program. The sequence of opera- 
tion for loading your secondary index with an application program is 
described here. 

A secondary file has the following format* 



Secondary Sequence Primary 
Key Number Key 



•—^ bytes—* 



Relative 

Block 

Number 



SMITH 


0001 


12345AB 


REN 






4 bytes 






In preparation for loading your secondary index> allocate the following 
sort data sets^ 

• Sort input data set 

• Sort output data set 

• Sort work data set. 

The size of the records in the input and output data sets is calculated 
using the lengths of keys from the primary index file record plus four 
bytes for the sequence number and four bytes for the RBN. 




If you have the Sort/Merge licensed program product* program number 
5719-SM2, refer to the IBM Series/l Event Driven Executive Sort/Merge 
Programmer's Guide > SL23-0016/ for details of the sort work data set and 
sort specification data sets. Otherwise* use your own sort program. 

Loading your secondary index requires the following sequence: 

1. Open the primary index file in process mode. 

2. Retrieve a primary index file record with a GETSEQR request (re- 
trieves the primary record plus the RBN). 

a. Ulhen end-of-data condition is reached* go to step 6. 



\^ 
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3. Using values from the retrieved records build a secondary record 
Mith the folloMing format ^ 



Secondary Double word Primary 
Key of X'OO* Key 



Primary 
RBN 





0000 







' — ^ bytes — ' 






4 bytes 









5. 
6. 



8. 

9. 
10 



Move the neuily built secondary record into the sort input data set. 

Return to step 2 and repeat the sequence. 

Sort the records in the sort input data set using the folloMing sort 
speci f i cati ons, 

a. Sort the input records on position 1 through n-4 into ascending 
sequence (n= the length of the records as calculated previously 
for the sort data sets). 

Open the secondary index, Mhich is to be loaded* in load mode. 

If your program is written in Event Driven Language (EDL)> specify 
the independent option when you open the secondary index. If you 
are using a high level language* use $IAMUT1 to turn on the inde- 
pendent indicator. 

Read a record from the sorted output. 

a. Uhen end-of-file is reached* go to step 14. 

Move a sequence number into the retrieved record's sequence number 
field (use X'OOOO' for the first record). 



Increment the sequence number by a value of 1. 

11. Use a PUT request to load the record into the secondary file. 

12. Return to step 8 and repeat the sequence. 

13. Issue a DISCONNECT to the primary index file and secondary index. 

14. Using the $IAriUTl utility* turn off the invalid indicator for this 
secondary index entry in your directory. Also* turn off the inde- 
pendent indicator if you turned it on in step 7. 
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CHAPTER 6. ALLOCATING INDEXED FILES FROM AN APPLICATION PROGRAH 



This chapter describes hoN to allocate and format primary or secondary 
indexed files from an application program using the Indexed Access Meth- 
od. Related performance considerations are covered under "Other Per- 
formance Considerations" on page 11-6 in Chapter 11. 

Use the load module^ $IAMUT3, to allocate and format a primary or sec- 
ondary indexed file. The parameters you must supply to $IAMUT3 are sim- 
ilar to those required uihen using option 2 of the SET parameters command 
(SE) for ^lAMUTl. $DISKUT3 must exist on the IPL volume before you can 
successfully allocate a file. 

If you Mant to define a secondary indexed file using $IAMUT3» you must: 

• Verify that lANQCB has been included in your system. 

• Be sure the related primary file already exists on the volume speci- 
fied in its entry in directory data set $IAMDIR. 

• Use the $IAMUT1 utility to create an entry for the new secondary 
file in the directory data set $IAMDIR. 

The data set to be allocated and formatted as an indexed file must not 
already exist on the specified volume. If it does^ $IAMUT3 sets an error 
return code in the IDEFIAMR return code field of the parameter list. 

Load module $IAMUT3 requires approximately IIK bytes of storage for exe- 
cution. This includes 2K bytes of dynamic storage that $IAMUT3 requires 
for the default maximum block size. For a block size that is greater 
than 2K (2048 decimal bytes), you can allocate the necessary dynamic 
storage in $IAriUT3 by one of two methods^ 

• Set the "ST0RA6E='' parameter of the LOAD instruction that loads 
$IAMUT3 to the desired number of decimal bytes (the block size of 
the file). 

• Use the SS (Set Storage) command of $DISKUT2 to set the dynamic 
storage for $IAMUT3 to the desired number of decimal bytes before 
loading $IAMUT3 from your program. 



CALL LOAD MODULE $IAMUT3 

Use the LOAD instruction to load $IAMUT3 into storage for execution. 
Your program can load $IAMUT3 into any partition. If the LOAD operation 
is successful, your program should issue a WAIT instruction to wait for 
$IAriUT3 to end. 

The following example illustrates the use of the LOAD instruction to 
call $IAMUT35 




This example, assumes that $IAMUT3 exists on the IPL volume. 

IDEFADDR is the parameter that you pass to $IAMUT3. It is the address 
of the parameter list that contains the file definition parameters. 
This parameter list is mapped by the IDEFEQU copy code. See "$IAMUT3 
Parameter List" on page 6-6 for further information. 

IDEFECB is an event control block in your program. It is posted when 
$IAMUT3 completes. 
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LOGMSG=NO specifies that the "Program Loaded" message is not to be dis- 
played or printed on the terminal. 

PART=ANY specifies that $IAI1UT3 can be loaded into any partition that 
has enough storage for it. 

The sample program folloNing this section illustrates the use of the 
LOAD and UAIT instructions in a program that loads $IAMUT3. 



$ZANUT3 SAMPLE PROGRAM 



The folloMing sample program uses the load module $IAMUT3 to allocate 
and format a primary indexed file named lAMPRIOl on volume EDX003. 

The first TCBGET instruction places the TCB address of the user task 
into the parameter list. The second TCBGET instruction places the 
address space of the user task into the parameter list. 

The second LOAD instruction attempts to load $IAMUT3 into any partition. 

If the LOAD operation is successful, the WAIT instruction is issued to 
wait for $IAMUT3 to finish. The sample program then displays the 
Indexed Access Method return code and the system return code from the 
parameter list. 

An Indexed Access Method return code of -1, in this case. Mould indicate 
that the indexed file has been successfully allocated and formatted for 
50 base records with immediate write-back of data blocks to the file. 



^fcuiii^'^ 
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SAMPLE PROGRAM 
START EQU 



TCBGET 
TCBGET 



START 



DEFUTCB,$TCBVER 
DEFUADS,$TCBADS 



A(TCB OF USER TASK) 
ADDRESS SPACE OF USER TASK 



LOAD $IAMUT3 INTO ANY PARTITION 

LOAD $IAMUT3,IDEFADDR,EVENT=IDEFECB,L0GMSG=N0,PART=ANY 



MOVE RTCODE, SAMPLE 



SAVE SYSTEM RET CODE OF LOAD 



IF (RTCODE, NE,+SUCCESS) IF LOAD WAS NOT SUCCESSFUL 

PRINTEXT 'LOAD FAILED FOR $IAMUT3, RETURN CODE = •,SKIP=2 
PRINTNUM RTCODE, TYPE=S,FORMAT=( 4, 0,1) 
GOTO ENDIT END THE TEST CASE 

ENDIF END TEST FOR UNSUCCESSFUL LOAD 

WAIT IDEFECB WAIT FOR $IAMUT3 TO FINISH 

PRINTEXT »$IAMUT3 HAS COMPLETED PROCESSING' ,SKIP=2 

PRINTEXT 'INDEXED ACCESS METHOD RETURN CODE = ',SKIP=1 

PRINTNUM DEFIAMR,TYPE=S,FORMAT=C4,0,I) lAM RET CODE 

PRINTEXT 'SYSTEM RETURN CODE = ',SKIP=1 

PRINTNUM DEFSYSR,TYPE=S,FORMAT=(4,0,I) SYSTEM RET CODE 



EQU X 
PROGSTOP 

DATA DEFINITION AND STORAGE AREAS: 



ENDIT 

SUCCESS EQU 
RTCODE DATA 
IDEFADDR DATA 
IDEFECB ECB 

X IDEF PARAMETER LIST 

IDEFLIST EQU 
DATA 
DATA 
DATA 
DATA 
DATA 



-1 

F'O' 

A(IDEFLIST) 





DEFCNTR 
DEFBSRC 
DEFBKSZ 
DEFRCSZ 
DEFKYPS 

DEFFRER 
DEFFREB 
DEFKYSZ 

DEFRSVB 

DEFRSVI 

DEFFREP 

DEFDLTH 

DEFDYN 

DEFIAMR 

DEFSYSR 

DEFUTCB 

DEFUADS 

DEFSIZX 

DEFRES2 

X 

DEFDSNM 

DEFVOLN 



DATA 
DATA 
DATA 

DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 

DATA 
DATA 



0002' 

50' 

256' 

80' 

1' 



0' 
0' 
8' 

-1' 

0' 

-1' 

-1' 

-1' 

0' 

0' 

0' 

0' 

0' 

0' 



CLS'IAMPRIOl' 
CL6'EDX003' 



SUCCESSFUL COMPLETION RETURN CODE 
SYSTEM RETURN CODE OF LOAD 
ACUSER IDEF PARAMETER LIST) 
POSTED WHEN $IAMUT3 ENDS 



USER IDEF PARAMETER LIST 

NO EXTENTS, PRIMARY FILE, IMMED. WRITE-BACK 

NUMBER OF BASE RECORDS 

BLOCK SIZE IN BYTES 

RECORD SIZE IN BYTES 

KEY POSITION IN RECORD 

X FIRST BYTE OF RECORD IS 1 

FREE RECORDS PER DATA BLOCK 

FREE BLOCK (%). (DEFAULT) 

KEY SIZE IN BYTES 

RESERVE BLOCK (X). (DEFAULT) 

RESERVE INDEX (%). (DEFAULT) 

FREE POOL (%). (DEFAULT) 

DELETE THRESHOLD (%) . (DEFAULT) 

NUM. OF DYNAMIC FREE POOL BLOCKS (DEFAULT) 

lAM RETURN CODE WILL BE PLACED HERE 

SYSTEM RETURN CODE WILL BE PLACED HERE 

ADDRESS OF TCB OF USER TASK 

ADDRESS SPACE OF USER TASK 

SIZE OF EXTENTS 

RESERVED, MUST BE 

NAME OF DATA SET TO ALLOCATE 
VOLUME NAME FOR DATA SET 



ENDPROG 
END 
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$IANUT3 Return Codes 

$IAMUT3 places the system return code into the word labeled IDEFSYSR in 
your parameter list. This is the return code from any system function 
(such as READ or NRITE) that did not complete properly. 

If the system functions completed properly, or if no system functions 
Mere processed uhile $IAMUT3 was loaded, the IDEFSYSR word contains a 
return code of -1 (successful). 

After $IAMUT3 has completed processing, check the Indexed Access Method 
return code field (IDEFIAMR) before you check the system return code 
field. 



'Ly 
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$IAMUT3 places The folloMing Indexed Access Method return codes in the 
Mord labeled IDEFIAMR in your parameter list. 



^F>»^ 



Code Condition 

-1 Successful completion 

13 A required module is not included in load module $IAMUT3 

30 Inconsistent free space parameters uere specified 

31 FCB write error occurred during IDEF processing; check system 
return code 

32 Block size is not a multiple of 256 

36 Invalid block size during file definition processing 

37 Invalid record size 

38 Invalid index size 

39 Record size is greater than block size 

40 Invalid number of free records 

41 Invalid number of clusters 

42 Invalid key size 

43 Invalid reserve index value 

44 Invalid reserve block value 

45 Invalid free pool value 

46 Invalid delete threshold value 

47 Invalid free block value 

48 Invalid number of base records 

49 Invalid key position 

101 Write error occurred; check system return code 

130 No dynamic storage allocated for $IAMUT3 

131 Base records parameter is out of range 

132 Block size parameter is out of range 

133 Record size parameter is out of range 

134 Key position parameter is out of range 

135 Free records per data block parameter is out of range 

136 Dynamic blocks parameter is out of range 

137 Data set already exists 

138 Open failed in $DISKUT3 (other than Data Set Not Found); 
check system return code 

139 Allocate failed in $DISKUT3. Check system return code 
201 The primary file for this secondary file could not be 

opened; Check system return code 
210 $DISKUT3 could not be loaded; check system return code 

230 Directory read error for $IAMDIR; Check system return 
code and verify that the directory exists 

231 $IAMQCB not found; Check operating system generation 
listing for $IAMQCB include statement. 

232 Open failed for directory data set $IAMDIR; check system 
return code and verify that the directory exists 

233 Directory related primary request is a primary entry 

234 Data set name and volume name not found in directory 
data set $IAMDIR 

248 I/O error on primary file during a secondary request; 
check system return code 
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Error Logging and Reporting 

$IAMUT3 logs all positive Indexed Access Method return codes (errors) 
returned by the indexed file allocation function. 

The $LOG utility should be loaded on your system before you execute the 
program that loads $IAMUT3. 

To list the Indexed Access Method error log entries currently in the 
system error log data set» load the $ILOG utility program using the $L 
system command. Respond to the prompt "(DSNAME» VOLUME) s" Nith the system 
error log data set name and volume name. 

$IAMUT3 error conditions are recorded on the log report with a function 
code of "IDEF". 

The following is a sample of the $IL06 error report showing two error 
records from $IAMUT35 



INDEXED ACCESS METHOD LOG REPORT PROGRAM ACTIVE 
TCB ORIG CURR $IAM SYSTEM 



PTN 


ADDR 


DSNAME 


VOL 


FNCTN 


FNCTN 


RTCODE 


RTCODE 


DATE 


TIME 


8 


0680 


IAMSEC05 


EDX003 


IDEF 


IDEF 


31 


5 


06/22/84 


11:52:10 


2 


0530 


IAMPRI02 


EDX003 


IDEF 


IDEF 


137 


-1 


06/22/84 


11:20:55 



2 INDEXED ACCESS METHOD LOG ENTRIES LOCATED 
$ILOG ENDED 



Load module $IAMUT3 also includes the system task error exit routine L J 

$$EDXIT. This routine: ^-^ 

• Captures relevant data from the program header^ task control blocks 
and hardware status area when an exception occurs. 

• Formats and prints this data on $SYSLOG and $SYSPRTR. 

• Displays an error message on the loading terminal. 

Most of $IAMUT3 is written in Series/1 assembler language^ so the con- 
tents of general registers RO through R7 may not correspond to their 
headings in the printout that $$EDXIT creates. 

Refer to the EDX library publications for additional information about 
$$EDXIT. 



$IAMUT3 Parameter List 

When your program loads $IAMUT3 into storage^ it passes the address of a 
parameter list that defines the characteristics of the indexed file you 
want to allocate and format. This parameter list must be in the same 
partition as the program that loads $IAMUT3. The IDEFEQU copy code maps 
this parameter list. 

Refer to "Option 2" on page 9-34 for information on the SE command of 
the $IAMUT1 utility program. It describes the parameters that define an 
indexed file. 



o 
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The folloMing chart shous each field in the IDEFEQU parameter list» 
whether it is set by the user (U) or by $IAMUT3 (S), its corresponding 
parameter name from option 2 of the SE command of $IAMUT1> and a brief 
description of the fields 



IDEFEQU 


Set 


SE Option 


2 


Field Name 


By 


Parameter 


Descri pti on 


IDEFCNTR 


U 


None 


Flag bits for primary or secondary file* 
and immediate Mrite-back of data blocks. 
See figure beloM for equates. 


IDEFBSRC 


U 


BASEREC 


Number of base records. For default* code 
D'-l' (when IDEFDYN is not D'-l'). 


IDEFBKSZ 


U 


BLKSIZE 


Block size in bytes. 


IDEFRCSZ 


U 


RECSIZE 


Record size in bytes. For a secondary file* 
CODE F'O'. 


IDEFKYPS 


U 


KEYPOS 


Key position in record. First byte of 
record is 1. For a secondary file, this is 
the position of the secondary key in the 
primary record. For default* code F*l'. 


IDEFFRER 


U 


FREEREC 


Number of free records per data block. For 
default, code F'O*. 


IDEFFREB 


U 


FREEBLK 


Free block (%). Can be 0-99. For default, 
code H'O'. 


IDEFKYSZ 


U 


KEYSIZE 


Key size in bytes. For a primary file, can 
be 1-25^. For a secondary file, can be 
1-250 (size of the secondary key in the 
primary record). 


IDEFRSVB 


U 


RSVBLK 


Reserve block (%). Sum of IDEFFREB and 
IDEFRSVB. Must be less than 100. 
For default, code H'-l». 


IDEFRSVI 


U 


RSVIX 


Reserve index (%). Can be 0-99. 
For default, code H'O'. 


IDEFFREP 


U 


FPOOL 


Free pool (%). Can be 0-100. For default, 
code H'-l». 


IDEFDLTH 


U 


DELTHR 


Delete threshold (%). Can be 0-99. For 
default, code H»-l» . 


IDEFDYN 


U 


DYN 


Number of dynamic free pool blocks. For 
default, code D'-l". 


IDEFIAMR 


S 


None 


lAM return code will be placed here. 


IDEFSYSR 


S 


None 


System return code will be placed here. 


IDEFUTCB 


U 


None 


Address of TCB of user task. 


IDEFUADS 


U 


None 


Address space of user task. 


IDEFSIZX 


U 


None 


Size of extents. 


IDEFRES2 


U 


None 


Reserved (must be ) . 


IDEFDSNM 


U 


None 


Name of data set to allocate. 


IDEFVOLN 


U 


None 


Volume name for data set. 



o 



IDEFEQU 


Bit 


Descripti on 


IDEFEXT 


^ 


Data set type 

If 1, data set is extendable 

If 0, data set is not extendable 


IDEFSEC 


12 


File type flag 

If 1, file is secondary 

If 0, file is primary 


IDEFIMDU 


14 


Data block write back flag 
If 1, immediate write back 
If 0, no immediate write back 
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CHAPTER 7. PROCESSING THE INDEXED FILE 



This chapter provides information for designing applications that use 
the Indexed Access Method. It contains information about: 

• Task priorities 

• Connecting and disconnecting the indexed file 

• Accessing the indexed file 

• Maintaining the indexed file. 

Chapter B, "Coding the Indexed Access Method Requests** on page 8-1 con- 
tains a detailed description of the EDL coding syntax of each Indexed 
Access Method request. You may wish to refer to it uihile reading this 
chapter. 



TASK PRIORITIES 



$IAM executes at a priority of 100. Applications that issue requests to 
$IAM must execute at a priority equal to or beloM that of $IAM. Unpre- 
dictable results can occur if a user task is executing at a higher pri- 
ority. 






CONNECTING AND DISCONNECTING THE INDEXED FILE 

An indexed file must be defined and formatted by using the $IAMUT1 util- 
ity set parms (SE) and define (DF) commands before issuing a LOAD or 
PROCESS request to the file. 

Prior to using an indexed file, you must issue either a LOAD or PROCESS 
request to connect it to your program. The file must be defined in your 
PROGRAM statement or by a DSCB statement. A CALL statement specifying 
either LOAD or PROCESS automatically opens the Indexed Access Method 
file. If you have an already open DSCB for the Indexed Access Method 
file you can pass it as a parameter, but that is not required. 

However, if the indexed file has already been connected to any program 
by a LOAD or PROCESS request, make sure that the DSCB passed on any sub- 
sequent LOAD or PROCESS request for this indexed file contains the data 
set name and volume name before you issue the request. 



%^ 
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CONNECTING 



A LOAD or PROCESS request builds an indexed access control block (lACB) 
that is associated uith an indexed file. The lACB connects a request to 
the file. 

In load mode* data records are placed in the file sequentially (free 
records and blocks are skipped). Uhen in process mode» data records are 
placed in the first appropriate slot in the file (free space is used) 
unless the record has a new high key. In the case of a new high key* 
the record is placed in the next available base record slot. 



Only one LOAD request can be active for a given file, 
ing can take place concurrently Mith loading. 



HoMever» process- 



Multiple lACBs can be associated Mith the same file. Data integrity is 
maintained by a locking system that assigns file locks* record locks* or 
block locks to the requesting lACB. This prevents concurrent modifica- 
tion of index or data records* thereby avoiding the possibility of a 
double update situation. 

Some applications uiill need to wait for a lock to be released on a 
record, block* or buffer. In these situations you might want to use the 
conditional requests available for some Indexed Access Method functions. 
The conditional function requests allow control to be returned imme- 
diately to the requesting program for other processing* then return lat- 
er to attempt to retrieve the record which was locked. The conditional 
requests are described in Chapter 8, "Coding the Indexed Access Method 
Requests" on page 8-1. 

An lACB can hold only one lock at a time* if your application requires 
concurrent execution of functions that obtain locks (direct update or 
sequential update - see "Accessing the Indexed File" on page 7-4 for a 
description of these functions)* you must issue multiple PROCESS 
requests to build multiple lACBs. 



V-.y 



DISCONNECTING 



A DISCONN request disconnects an lACB from the file* releases the stor- 
age for that lACB* releases locked blocks or records being held by that 
lACB* and writes out to disk any blocks that are being held in the buff- 
er. The DISCONN request can be issued at any time during loading or 
processing. 

There is no automatic DISCONN on task termination. Failure to discon- 
nect your indexed files prior to task termination may prevent resources 
that were allocated to your task from being allocated to other tasks and 
updated records from being written to your file. 
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using Secondary Keys 

To access a file by a secondary key^ you issue either a LOAD or PROCESS 
requests specifying the file name of the secondary index and specifying 
secondary keys Mhen referencing data records. The Indexed Access Method 
determines the relationships among the files by using the directory and 
automatically opens the primary file. All subsequent operations done 
under this LOAD or PROCESS access the file using the secondary index. 
You must open a file by the primary name to access it by the primary 
keys. 

Direct retrievals use the secondary index» and sequential retrievals 
return records in order by secondary key. Records within a group which 
have the same secondary key are returned in the order which the records 
were written into the file. Each application must determine whether the 
correct record has been retrieved when duplicate keys are possible; the 
Indexed Access Method provides no facility for that determination. 

Uhen records are updated, inserted, or deleted, in primary index files, 
some or all secondary indexes can be updated automatically according to 
the options you selected in the directory entries. These options are^ 
auto-update and independent processing. 

If the auto-update indicator is on in the directory entry for a second- 
ary index and you open the associated primary file to insert, delete, or 
update records* 

• the associated secondary index will be updated automatically. There 
is no consideration for whether the independent indicator is on for 
the secondary. However, if the invalid indicator for the secondary 
entry is on, the secondary index is not updated. 

• use only conditional requests. To do this, code those requests that 
modify the file as DELETEC, PUTC, PUTDEC, or PUTUPC. Conditional 
requests are described in Chapter 8, "Coding the Indexed Access 
Method Requests" on page 8-1. 

The independent indicator is used when a secondary index is opened in 
load mode to add new entries to the file. 

Note: When records are accessed by their secondary key, you must 
ascertain through your application program that you have retrieved 
the correct record because of the possibility of duplicate keys. 
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ACCESSING THE INDEXED FILE 

Issue a PROCESS request to access an indexed file. After the PROCESS 
request has been issued^ any of the following functions can be 
requested: 

• Direct reading - Retrieving a single record independently of any 
previous request. 

• Direct updating - Retrieving a single record for update; complete 
the update by either replacing^ deleting^ or releasing the record. 

• Sequential reading - Retrieving the next logical record relative to 
the previous sequential request. 

The first sequential request can access the first record in the file 
or any other record in the file by key (except COBOL applications). 

• Sequential updating - Retrieving the next logical record for update; 
complete the update by either replacing, deleting, or releasing the 
record. 

• Inserting - Placing a single record, in its logical key sequence, 
into the indexed file. 

• Deleting ~ Removing a single record from the indexed file, 

• Extracting - Extracting data that describes the file. 

• Direct Block Reading - Retrieving a data block independent of any 
previous request. 

• Sequential Block Reading - Retrieving the next logical data block 
relative to the previous direct or sequential block-read request. 

jf — X 
Note that the update functions require more than one request. n ] 

Ulhen a function is complete, another function may be requested, except 
that a sequential processing function may be followed only by another 
sequential function. You can terminate sequential processing at any 
time by issuing a DISCONN or ENDSEQ request. An end-of-data condition 
also terminates sequential processing. 



DIRECT READING 

Use the GET request to read a record using direct access. The key 
parameter is required and must be the address of a field of full key 
length regardless of the key length specification. 

The record retrieved is the first record in the file that satisfies the 
search argument defined by the key and key relation (krel) parameters. 
The key field in your program is updated to reflect the key contained in 
the record that satisfied the search. 

If the key length is specified as less than the full key length, only 
part of the key field is used for comparison when searching the file. 
For example, the keys in a file are AAA, AAB, ABA, and ABB, the key 
field contains ABO» and key relation is EQ. If key length is zero, the 
search argument defaults to the full key ABO and a record-not-found code 
is returned. If the key length specification is 2 and the search argu- 
ment is AB, the third record is returned. If the key length 
specification is 1 and the search argument is A, the first record is 
returned. 
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DIRECT UPDATING 



^^,^ 



To update a record using direct access^ 

1. Retrieve the record with a GET request » specifying the key and key 
relation (krel) parameters. 

2. Complete the update by doing one of the following^ 

• If you want to change the records modify the record in your 
buffer (do not change the key field of the record). Issue a 
PUTUP request to return the updated record to the file. 

• If you do not want to change the records issue a RELEASE 
request. 

• If you Mant to delete the records issue a PUTDE request. 

The key parameter must be specified as the address of a field of full 
key length. The primary key cannot be modified during the update; a 
secondary key can. 

The only valid requests^ other than DISCONN and EXTRACT, that can follou 
GET for direct update are PUTUP, PUTDE, and RELEASE. 

During the update, the subject record is locked (made unavailable) to 
any other request until the update is complete. Even if no action is 
taken after the GET request is issued, the RELEASE request is required 
to release the lock on the record. You may wish to use the conditional 
option on your requests to avoid unnecessary wait for locks. For condi- 
tional request coding see Chapter 8, "Coding the Indexed Access Method 
Requests" on page 8-1. For details on long lock time or dead lock con- 
dition, see "Deadlocks and the Long-Lock-Time Condition" on page 12-10. 
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SEQUENTIAL READING 



Use the GETSEQ request for sequential access to records. After a 
sequential processing request has been initiated, only sequential func- 
tions can be requested until an end-of-data condition occurs or an 
ENDSEQ request is issued. Processing is terminated when a DISCONN 
request is issued or an error or warning is returned- 

— Fig 'prot* unknown — summarizes the protocol for sequential process- 
ing. 

Note: You can sequentially process a file more than once. 

To begin sequential access with the first record in a file, set the key 
address to zero. To start with any other record, specify a search argu- 
ment by specifying the key and key relation (krel) parameters. 

If you specify a search argument, the key field is modified to reflect 
the key of the first record found. 

After the first retrieval, a GETSEQ retrieves the next sequential record 
regardless of any key or key relation specification. Therefore, you can 
use the same GETSEQ statement to retrieve all records. A search argu- 
ment on succeeding retrievals is ignored and the key field is not modi- 
fied. 






Chapter 7. Processing The Indexed File 7-5 



Mhen using secondary keys» you access the duplicate keys with a sequen- 
tial get request. For example: 

GETSEQ SMITH 

Issuing the same request repeatedly will return all of the secondary 
keys whose value is SMITH. You must check to determine when the key 
changes^ or when you have retrieved the particular record you want with- 
in that sequence of keys. 

Specify ENDSEQ to stop reading before the end of data is reached. Read- 
ing ends automatically at the end of data. The end-of-data condition 
occurs when an attempt is made to retrieve a record after the last 
record in the file. 

If you specify the end-of-data exit (EODEXIT) parameter on the PROCESS 
requests control is transferred to the address specified by the EODEXIT 
parameter when the end-of-data condition occurs. 

During sequential reading* the block that contains the record is locked* 
making all records in the block unavailable to other requesters until 
the last record of the block is processed or sequential processing is 
ended. For details on long lock time or dead lock condition* see "Dead- 
locks and the Long-Lock-Time Condition" on page 12-10. 



SEQUENTIAL UPDATING 



To update a record using sequential access^ 

1. Retrieve the record with a GETSEQ request for update* specifying the 
key and one of the update key relation (krel) parameters. The key 
is used only on the first retrieval. Do not specify a key if proc- 
essing is to begin with the first record in the file. /T 



2. Complete the update by doing one of the following: 

• If you want to change the record* modify the record in your 
buffer (do not attempt to change the primary key field of the 
record). Issue a PUTUP request to return the updated record to 
the file. 

• If you do not want to change the record* issue a RELEASE 
request. 

• If you want to delete the record* issue a PUTDE request. 

During sequential updating* the block that contains the record is 
locked* making all records in the block unavailable to other requesters 
until the last record of the block is processed or sequential processing 
is ended. 



\J 
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Terminate processing Mith an ENDSEQ request or a DISCONN request either 
before or after completing the update. Processing is also terminated on 
an end-of-data condition. 



INSERTING RECORDS 



To insert a neM record in a file» issue a PUT request after the file has 
been connected Mith a PROCESS. The Indexed Access Method uses the pri- 
mary key of the record to insert the record into the file. 

The primary key of the inserted record must be different from any key in 
the file; otherMise» a duplicate key error occurs. The key can be high- 
er than any key in the file. 

If you are not loading base records^ and Mant to insert records into the 
file in random orders the following should be satisfied: 

• For files defined by option 1» ensure that random (R) was specified 

• For files defined by option 2» ensure that sufficient free pool 
space was specified. 



DELETING RECORDS 






Use DELETE to delete a record from the file. Specify the full key of 
the record. If no record exists with the specified key» a warning 
return code is returned. 



EXTRACTING INDEXED FILE INFORMATION 

The EXTRACT request provides information about a file from the file con- 
trol block (FCB) or FCB Extension. It can also return data paging sta- 
tistics to the calling program with an option to reset the counters. 
Data paging is described under "Data Paging" on page 11-3. 

The FCB includes information such as key lengths key displacements block 
sizes record size> and other data regarding the file structure. The FCB 
Extension contains the $IAMUT1 utility SE command parameters that were 
used to define the file. 

The EXTRACT request copies the file control block or the FCB Extension 
to an area that you provide. The file must have been connected by a 
LOAD or PROCESS request. 

The contents of the FCB block and the FCB Extension are described by 
FCBEQUs a unit of copy code that is supplied with the Indexed Access 
Method. Use COPY FCBEQU to include these equates in an EDL program. 

An EXTRACT issued for a secondary file returns the primary FCB with the 
secondary key size and position of the secondary key. If you want the 
actual FCB of the secondary file, you must open the secondary file inde- 
pendently and then the secondary index FCB will be returned for the 
EXTRACT request. The FCB extension returned is always the secondary FCB 
extension. 
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DIRECT BLOCK READING 



The Block I/O functions can help improve program performance. To use 
these features, you must supply a buffer area in your program and speci- 
fy on the PROCESS call that the file is to be opened in Block Mode. 
This causes data blocks to be read into the program's buffer instead of 
into the $IAM buffer pool. Subsequent record-level commands (such as 
GETf GETSEQ, and PUT) first check to see if the data record they laant is 
in the block in the buffer, and if so lAMFR (the JAM link module) per- 
forms the function. In many applications, this reduces the number of 
calls to $IAM. 

Tmo Block Mode commands are provided to allow even faster processing in 
some applications. The GETB request is similar to the GET request, but 
it returns to the program the entire block of data containing the record 
specified by the key. GETNB returns the next block of data (sequential- 
ly by key). By using these requests, your application program can read 
quickly through the data file sequentially, limiting direct and 
time-consuming use of the $IAM resource to call records already con- 
tained in the blocks obtained. 
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MAINTAINING THE INDEXED FILE 



o 



his section describes how to maintain Indexed Access Method files. 
olloNing topics are discussed^ 

File backup and recovery 

File recovery without backup 

Reorganizing the file 

Dumping the file 

Deleting the f i le 

Verifying an indexed file. 



The 






FILE BACKUP AND RECOVERY 

To protect against the destruction of data* copy the indexed file (or 
the volume in which the file exists) at regular intervals using the 
$COPY utility. See the Operator Commands and Utilities Reference manual 
in the EDX library for instructions on using the Event Driven Executive 
uti li ti es. 

To obtain a sequential dump of an indexed f i le» use the $IAMUT1 utility 
UN command. During the interval between making copies^ you should keep 
a journal file of all transactions made against the indexed file. 

The journal file can be a consecutive file containing records that 
describe the type of transaction and the pertinent data. A damaged 
indexed file can be recovered by updating the backup copy from the jour- 
nal file. 

For example, suppose an indexed file named REPORT is lost because of 
physical damage to the disk. The condition that caused the error has 
been repaired and the file must be recovered. Delete REPORT, copy the 
backup version of REPORT to the desired volume, and process the journal 
file to recreate the file. 

If a data-set-shut-down condition exists, cancel $IAM and reload it. 
Then issue a PROCESS to the REPORT file and, using the journal file, 
reprocess the transactions that occurred after the backup copy was made. 
For more information, see "The Data-Set-Shut-Down Condition" on page 
12-10. 



o 



Backing Up A Secondary Index 

A secondary index can be backed up the same as primary index files. 
However, if your primary file is backed up you can rebuild your second- 
ary from the backup copy of the primary indexed file. 

Duplicate secondary keys are maintained in the order they are inserted 
by a secondary key sequence number. This sequence number is incremented 
with each new insert. Ulhen a secondary index is reloaded the secondary 
key sequence numbers are reassigned. Therefore, the history of which 
records were written to the file first is lost. 

Note: If your application is dependent on the secondary key sequence 
number history, you would not want to rebuild your secondary index 
because the sequence numbers are reset. 
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RECOVERY UITHOUT BACKUP 



If you do not use the backup procedures as described previously under 
"File Backup and Recovery" on page 7-9> and you encounter a problem Mith 
your file* you still may be able to recreate your file. However* the 
status of requests that Mere in process at the time of the problem is 
uncertai n . 

To recreate your file, follow the steps in "Reorganizing an Indexed 
File" to reorganize your file. After recreating the file, verify the 
status of the requests that were in process when the problem occurred. 



REORGANIZING AN INDEXED FILE 

An indexed file must be reorganized when a record cannot be inserted 
because of lack of space. This condition does not necessarily mean that 
there is no more space in the file; it means that there is no space in 
the area where the record would have been placed. Therefore, you may be 
able to reorganize without increasing the size of the file. Perform the 
following steps to reorganize a file= 

1. Ensure that all outstanding requests against the file have been com- 
pleted; issue a DISCONN for every current lACB. 

2. Use the set parms (SE) or define (DF) commands of the $IAMUT1 utili- 
ty to define a new indexed file. Estimate the number of base 
records and the amount and mix of free space in order to minimize 
the need for future reorganizations. See Chapter 3, "Defining Pri- 
mary Index Files" for guidelines for making these estimates. 

You can use Option 3 of the SE command to define the new file like 

the original indexed file. r ) 



3. Use the reorganize command (RO) of the $IAMUT1 utility to load the 
new indexed file from the indexed file to be reorganized. 

Alternatively, you can use the unload command (UN) of the $IAMUT1 
utility to transfer the data from an indexed file to a sequential 
file, then use the load command (LO) to load it back into the 
indexed file. 

4. Use the $DISKUT1 utility to delete the old file and rename the new 
file. 

REORGANIZING A SECONDARY INDEX: Reorganizing a secondary index does not 
reset the secondary key sequence numbers during the reorganization. The 
records are placed in another Indexed Access Method file without any 
modification within the individual records. The secondary key sequence 
numbers will be reset however, when the index is loaded. 






DUMPING AN INDEXED FILE 



To produce a hexadecimal dump of an indexed file, use the DP command of 
the $DISKUT2 utility. The dump includes control information, index 
blocks, and data blocks. For information on the $DISKUT2 utility, refer 
to the Operator Commands and Utilities Reference manual in the EDX 
library. 
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DELETING AN INDEXED FILE 

Delete an indexed file the same uiay you delete any other file. From a 
terminals use the DE command of the $DISKUT1 utility; from a program^ 
use the $DISKUT3 data management utility. (Refer to the Operator Com- 
mands and Utilities Reference for a description of $DISKUT1» and to the 
Installation and System Generation Guide for a description of $DISKUT3. 
Both of these manuals are EDX library publications.) 



VERIFYING AN INDEXED FILE 

$VERIFY helps you check the validity of an indexed file and prints con- 
trol block and free space information about the file on $SYSPRTR. 

With $VERIFY you can: 

• Verify that all pointers in an indexed file are valid and that the 
records are in ascending sequence by key. 

• Print a formatted File Control Block (FCB) listing* including the 
FCB Extension block. The FCB Extension block contains the original 
file definition parameters. 

• Print a report showing the distribution of free space in your file. 

• Verify secondary files against primary files. 

For details on using $VERIFY, see Chapter 10, "The $VERIFY Utility" on 
page 10-1. 
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CHAPTER 8. CODING THE INDEXED ACCESS HETHOD REQUESTS 



This chapter describes the syntax used to code Event Driven Language 
requests for the Indexed Access Method. 

The information in this chapter is intended for use as a reference Mhen 
coding EDL application programs that use the Indexed Access Method. For 
information on coding Indexed Access Method applications in other lan- 
guagesy refer to the appropriate language manual. 

Included for each request is a description of the purpose of the 
requests the detailed coding syntax* a description of each parameter* 
and all of the return codes associated with using these requests. 

At the end of this chapter is a summary of the syntax of the EDL CALL 
instructions used to invoke the functions provided by the Indexed Access 
Method. 

For a complete example of using the Indexed Access Method requests* 
refer to Appendix 0, "Coding Examples" on page C-1. 
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REQUEST FUNCTIONS OVERVIEH 

This section provides an overvieM of the Indexed Access Method requests 
and hoM to code them. The Indexed Access Method callable requests Qre^ 



Request 

DELETE 

DISCONN 

ENDSEQ 
EXTRACT 

GET 
GETB 
GETNB 
GETSEQ 

LOAD 
PROCESS 



PUT 

PUTDE 
PUTUP 
RELEASE 



Description 

Deletes a single records identified by its key» from the file. 
Use DELETE to delete a record; the record cannot have been 
retrieved for update. 

Disconnects an lACB from an indexed file* thereby releasing 
any locks held by that lACB; writes out all buffers associated 
Mith the file; and releases the storage used by the lACB. 

Terminates sequential processing. 

Provides information about the file from the File Control 
Blocks File Control Block Extension^ and data paging statis- 
tics. 

Directly retrieves a single record from the file. If you 
specify the update mode* the record is locked (made unavail- 
able to other requests) and held for possible modification or 
deletion. Use GET to retrieve a single record from the file. 

Directly retrieves a block of data from a file that is opened 
in block rnode^ and puts it into a program buffer area. The 
block is locked until a request that requires another block is 
issued> or until a DISCONN request is made. 

Sequentially retrieves a block of data from a file that is 
opened in block mode» and puts it into a program buffer area. 
The block is locked until a request that requires another 
block is issued^ or until a DISCONN request is made. 

Sequentially retrieves a single record from the file. If you 
specify update mode» the block containing the record is locked 
(made unavailable to other requests) and held for possible 
modification or deletion. Use GETSEQ Mhen you are performing 
sequential operations. 

Builds an Indexed Access Control Block (lACB) and connects it 
to an indexed file. You can then use the lACB to issue LOAD 
requests to that file to load records. 

Builds an Indexed Access Control Block (lACB) and connects it 
to an indexed file. You can then use the lACB to issue 
requests to that file to ready update^ insert, and delete 
records. A program can issue multiple PROCESS functions to 
obtain more than one lACB for the same file, enabling the file 
to be accessed by several requests concurrently Mi thin the 
same program. 

Loads or inserts a new record depending on whether the file 
was opened with the LOAD or PROCESS request. Use PUT when you 
are adding records to a file. 

Deletes a record that is being held for update. Use PUTDE to 
delete a record that has been retrieved in update mode. 



Replaces a record that is being held for update, 
modify a record. 



Use PUTUP to 






Releases a record that is being held for update. Use RELEASE 
when a record that was retrieved for update is not changed. 



o 
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CODING INDEXED ACCESS METHOD REQUESTS 

All Indexed Access Method services Bro requested by using the CALL 
instruction. Parameters on the CALL instructions can have the folloMing 
forms* 

NAME: passes the value of the variable Mith the label *NAME* 

(NAME): passes the address of the variable *NAME* or the value of a sym- 
bol defined using an EQU statement 

For additional information, refer to the description of the CALL 
instruction in the Language Reference . 



General statement Format 

The general form of all Indexed Access Method calls is as follows; 



CALL IAM» (func) » iacb, (parm3) , ( pa rm<i) , (parmS) 



The request type is determined by the operand 'func'. In addition to 
the function request, you will notice that some functions allow a suffix 
of C, R, or OR. The C means perform the function requested condi- 
tionally. The condition is that the function is to be executed only if 
the record, the block containing the record, or the buffer containing 
the record is not locked. If any of those three items are locked for 
the record being requested, control is to be returned to the requesting 
program immediately. A return code is set to indicate that a lock was 
encountered. A conditional request can still wait on a resource if it 
is during the process of updating an index for a delete or insert. 

The appended character, R, means return the record and the relative 
block number (RBN) of the record being requested. Again this can be a 
conditional request by preceding the letter R with the letter C. The 
combination CR, indicates that the record and RBN is to be returned con- 
ditionally; return the record and RBN only if the record, block, or 
buffer is not locked by another request. 

If the RBN is requested and the record, block, and buffer are free, the 
RBN is returned as a ^-byte value. The 4-byte RBN value is returned at 
the end of the retrieved record. Therefore, when using the suffix R, 
ensure that your buffer is large enough to accommodate the record 
length, plus the 4-byte RBN value. 

The RBN can be used if you are building or maintaining your own second- 
ary index. However, because records in an indexed file are subject to 
being moved to different locations (RBNs) due to insert and delete 
activity, the RBN is not guaranteed to remain accurate if insert and 
delete activity to the primary index file occur. 

The option of C, R, or CR is indicated in the boxed instructions with a 
vertical bar (|). The presence of this bar indicates that a choice must 
be made. Only one of the requests can be used in any one statement. 
For example, PUTjPUTC, you must choose one or the other when coding the 
request. 

Depending on the type of function the remaining parameters may or may 
not be required. The symbols used for func and parm5 are provided by 
EQU statements in the lAMEQU copy code module and are coded as shown in 
the syntax descriptions. These symbols are treated as addresses; there- 
fore the MOVEA instruction should be used if it is necessary to move 
them into a parameter list. 
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Since these symbols are equated to constants* they may also be manipu- 
lated using other instructions by prefixing them Mith a plus (-f) sign. 
Use the COPY statement to include lAMEQU in your program. 

Note: You can not use the software registers (tl and #2) on Indexed 
Access Method calls. 



Using Program Variables 

If you use variables for parameters parm3» parm^» and parmS (that is» 
you code them without parentheses or a plus sign)* they are set to zero 
by the Indexed Access Method before returning. Those parameters must be 
reinitialized before executing the CALL instruction again. 



Link-edit Considerations 

Programs which call the Indexed Access Method must be processed by 
$EOXLINK to include the subroutine module lAM. lAMEQU has an EXTRN 
statement for lAM. In addition, programs which use the block I/O fea- 
tures of this product must include another link module^ $IAMFR. Refer 
to the Installation and System Generation Guide for information on 
$EDXLINK and how to perform the link-edit process. Refer also to the 
Operator Commands and Utilities manual for a description of the $EDXLINK 
utility. Both of these manuals are EDX library publications. 



Return Codes 



All Indexed Access Method requests pass a return code reflecting a con- 
dition that prevailed when the request completed. This code is passed 
in the task code word (referred to by task name) of the TCB associated 
with the requesting task. These return codes fall into three 
categori es' 



-1 = Successful completion 

Positive = Error 

Negative = Marning (other than -1) 



Note: Return codes 1* 7, 8, and 22 are positive value return codes but 
they do not cause the error exit routine to be entered* even when 
ERREXIT is coded. Also the negative (warning) return codes do not cause 
error exits. For details on coding ERREXIT, see "LOAD - Open File for 
Record Loading" on page 8-25, or "PROCESS - Open File" on page 8-29. 

The return codes associated with each request are included with the 
description of the request. 

The Indexed Access Method also has the capability of logging errors in 
the system error log. Automatic updates for secondary indexes could 
encounter several errors within one request. These errors will be 
logged in the system error log if $L06 is active. This may provide 
additional information when analyzing €»rrors. 
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CALL FUNCTION DESCRIPTIONS 

The Indexed Access Method CALL functions are described on the folloMing 
pages and are arranged in alphabetic order. 



DELETE - DELETE RECORD 

The DELETE request deletes a specific record from the file. The record 
to be deleted is identified by its key. The deletion makes space avail- 
able for a future insert. The file must be opened in the PROCESS mode. 

The DELETE/DELETEC request obtains a block lock to delete a record from 
a block. In order to obtain a block lock Mithout Maiting^ there can be 
no other block lock or record locks in effect for the block. 

The DELETEC request deletes a specific record from the file only if the 
record* block* or buffer is not locked. 

gypta)^: 



label CALL lAM, (DELETE|DELETEC), iacb, (key) 

Required: all 
Defaults: none 



o 



operands Description 

iacb The label of a Mord containing the lACB address returned by 
PROCESS. 

(key) The label of your key area containing the full key identifying 
the record to be deleted. 
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DELETE Example 

Tho following axample doletos the racord Mhos« key is 'KEYOOOl' from the 
file. The file is identified by the field named *FILE1*. 



CALL lAM, (DELETE). FILElf(KEY) 



FILEl DATA F»0» lACB ADDRESS FROM PROCESS 
KEY TEXT 'KEYOOOl*, LENGTH=7 



DELETE Return Codes 



Code 



Condition 



-1 Successful 
-58 Record not found 
-85 Record not found 

-90 Request cancelled because the request Mas conditional 
and a Mait on a lock or buffer Nould be required 

7 Link module in use, synchronize use of link 
module Mith the program 

8 Load error for $1AN, verify $IAri exists and enough 
storage is available to load it 

10 Invalid request 

12 Data set shut down due to error; see Chapter 12, 
'Error Recovery ' 

13 A required module is not included in $IAM 

14 Invalid index block found - during processing an 
incorrect index block type Mas found, recreate the file 

22 Address supplied by your program is not a valid lACB 
76 DSOPEN error occurred - The system error field in the 
OPEN table contains the DSOPEN error: 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

80 birite error - FCB. See system return code 

100 Read error - check system return code 

101 Mrite error - check system return code 

230 Directory read error for $IAMDIR - check system return code 
242 Secondary index is out of sync Mith primary file. 
Must rebuild file to get back in sync 

244 Error in opening auto-update file on secondary modification 
request 

245 Auto update PUTDE to a secondary failed. 
Auto-update processing continues 

247 During auto-update processing a GETSEQ to a secondary 
failed, auto-update processing continues 
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DISCONN - CLOSE FILE 



o 



The DISCONN request disconnects an lACB from an indexed file and 
releases the storage used for the lACB. It releases any locks held by 
that lACB and urites out any modified blocks from the file that are 
being held in the system buffer. Other users connected to this file are 
not affected. 



Syntax' 



label 



CALL 



Required^ all 
Defaults* none 



lAM, (DISCONN), iacb 



Operands Description 

iacb The label of a word containing the lACB address returned by 
PROCESS or LOAD. 



DISCONN Example 



o 



The folloMing example closes the file identified by the field named 
'FILEl'. 



CALL lAM, (DISCONN), FILEl 



FILEl DATA F'O' IACB ADDRESS FROM PROCESS 
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DISCONN Return Codes 



Code 



Condition 



-1 
7 



12 

13 
22 

100 
101 
110 



Successful 

Link module in use* synchronize use of link 

module Mith the program 

Load error for $IAM» verify $IAM exists and enough 

storage is available to load it 

Data set shut doun due to error; see Chapter 12* 

'Error Recovery ' 

Module not included in load module $IAM 

Address supplied by your program is not a valid lACB 

Read error - check system return code 

Urite error - check system return code 

Ulrite error* file closed 
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ENDSEQ - END SEQUENTIAL PROCESSING 

The ENDSEQ request ends sequential processing^ during which a block is 
locked and fixed in the system buffer. Sequential processing is 
normally terminated by an end-of-data condition. The ENDSEQ request is 
useful for freeing the locked block when the sequence need not be com- 
pleted. ENDSEQ is valid only during sequential processing. 

Note: After sequential processing has been terminated^ it can be 
restarted again anywhere in the file. 

Syntax* 



o 



label 



Requi red' 
Defaults: 



CALL 



all 
none 



JAM, (ENDSEQ), iacb 



Operands Description 

iacb The label of a word containing the lACB address returned by 
PROCESS. 



ENDSEQ Example 






The following example ends sequential processing for the file identified 
by the field named »FILE1». 



CALL lAM, (ENDSEQ), FILEl 



FILEl DATA F'O 



IACB ADDRESS FROM PROCESS 
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ENDSEQ Return Codes 



Code 


Condition 


-1 


Successful 


7 


Link module in use, synchronize use of link 




module Mith the program 


8 


Load error for $IAM> verify $IAM exists and enough 




storage is available to load it 


10 


Invalid request 


12 


Data set shut down due to error; see Chapter 12, 




•Error Recovery * 


13 


A required module is not included in $XAM 


22 


Address supplied by your program is not a valid lACB 



\J 
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EXTRACT - GET FILE INFORMATION 

Tha EXTRACT function returns information to the calling program. On a 
specific cally it performs one of the folloMing: 

• Returns information from a File Control Block (FCB). The FCB con- 
tains such things as the block size^ key lengtht and data set and 
volume names of the indexed file. The FCBEQU copy code module con- 
tains a set of equates to map the File Control Block. 

An EXTRACT request issued for a secondary file returns the primary 
FCB Mith the secondary key size and key position for the secondary 
index. If you Mant the FCB of the secondary file» you must open the 
secondary index uiith the independent option then the secondary index 
FCB Mill be returned. The FCB extension returned is always the FCB 
extension for the secondary index. 

• Returns information from a File Control Block Extension. The FCB 
Extension contains the parameters used to define the file. The 
FCBEQU copy code module contains a set of equates to map the FCB 
Extension. 

• Returns data paging statistics. These can be used to calculate page 
"hit" ratios. 

• Returns data paging statisticSf then resets them to begin accumulat- 
ing new statistics. 



Syntax 



o 



label CALL JAM, (EXTRACT) , iacb, (buff ),( size) , (type) 

Required: iacb (only if type is FCBNRM or FCBEXT) 

buff 
Defaults: size = Full FCB 

type = FCBNRM 



Operands Description 

iacb The label of a word containing the IACB address returned by 

PROCESS or LOAD. Required only if type=FCBNRM or FCBEXT; oth- 
erwise ignored. 

(buff) The label of the user area into which the data is returned. 

If type=FCBNRM or FCBEXT, the File Control Block is returned 
in this area. The area must be large enough to contain the 
requested portion of the FCB. Use the COPY statement to 
include FCBEQU in your program so that the FCB and FCB Exten- 
sion fields can be referenced by symbolic names. 

If type=PAGST or PAGSTR, the paging statistics are returned in 
this area. In this case, the size parameter is ignored, and 
this area must be 16 bytes in length to accommodate the sta- 
tistics. The paging statistics are returned in four 
double-word fields: 

1. Ur ite Miss Count 

2. Write Hit Count 

3. Read Miss Count 
<t. Read Hit Count 
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(size) Used only if type=FCBNRM or FCBEXT; otherMise ignored. The 

number of bytes of the FCB or PCS Extension to be copied. The 
size of the FCB is the value of the symbol FCBSIZE in the 
FCBEQU equate table. The size of the FCB Extension is the 
value of the symbol FCBXSIZ in the FCBEQU equate table. 
Either of these symbols can be coded as the size parameter. 

(type) Type of data to be returned. The folloMing are defined: 

FCBNRM Extract the FCB. 



FCBEXT Extract the FCB Extension. 

PAGST Returns data paging statistics to the buffer. 
alNays returns 16 bytes. 



It 



PAGSTR Same as PAGST# except the data paging statistics are 
reset to zero after being copied to the buffer. This 
alloMS a neM set of statistics to be accumulated. 



EXTRACT Examples 

The following example retrieves the current paging statistics and places 
then into the four double Mords provided. 



CALL IAMr(EXTRACT),0,(WRMIS),0, (PAGST) 



MRMIS 


DATA 


D'O' 


WRITE MISS COUNT 


WRHIT 


DATA 


D'O' 


WRITE HIT COUNT 


RDMIS 


DATA 


D'O' 


READ MISS COUNT 


RDHIT 


DATA 


D'O* 


READ HIT COUNT 






The following example gets the attributes of the file identified by the 
field named FILEl from the FCB and places them into an area called WORK. 



CALL I AM, ( EXTRACT) , FILEl , (WORK) , ( FCBSIZE) 



lACB ADDRESS FROM PROCESS 
FCB COPY AREA 
FCB EQUATES 



FILE 


DATA 


D'0» 


WORK 


DATA 


256F»0' 




COPY 


FCBEQU 



\y 
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EXTRACT Return Codes 



Code 



Condi ti on 



-1 
7 



12 

13 
22 
100 
120 
122 
123 



Successful 

Link module in use* synchronize use of link module with the 

program 

Load error for $IAM, verify $IAM exists and enough storage 

is available to load it 

Data set shut doMn due to error; see Chapter 12» 

'Error Recovery * 

A required module is not included in $IAM 

Address supplied by your program is not a valid lACB 

Read error - check system return code 

Invalid extract type 

File does not contain FCB extension 

Cannot extract paging statistics. Data paging not active 



^\ 
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GET - GET RECORD 



The GET request retrieves a single record from the indexed file and 
places the record in a user area. The file must have been opened using 
the PROCESS request before the GET request is issued. 

The requested record is located by key. The search may be modified by a 
key relation (krel) or a key length (klen). The first record in the 
file that satisfies the key condition is the one that is retrieved. 

Retrieve for update can be specified if the requested record is intended 
for possible modification or deletion. The record is locked and remains 
unavailable to any other requests until the update is completed by a 
PUTUP» PUTDE or by a RELEASE. The record is also released if an error 
occurs or processing is ended with a DISCONN. 

During an update^ you must not change the primary key field in the 
record or the field addressed by the key parameter. The Indexed Access 
Method checks for and prohibits primary key modification. 

The GETC request retrieves a single record from the indexed file and 
places the record in a user area only if the record, block, or buffer is 
not locked. 

The GETR request retrieves the RBN of a specified record from the 
indexed file and places the record and RBN in a user area. 

The GETCR request retrieves the RBN of a specified record from the 
indexed file and places the record and RBN in a user area only if the 
record, block, or buffer is not locked. 

Syntax' 



label 



Requi red: 
Defaults! 



CALL I AM, ( GET I GETC I GETR I GETCR), iacb,( buff), (key), 
(mode/krel ) 

iacb, buff, key 
mode/krel=EQ 



o 



Operands Description 

iacb The label of a Mord containing the IACB address returned by 
PROCESS. 

(buff) The label of the user area into which the requested record 
is placed. Uhen the RBN is requested, the RBN is returned 
at the end of the record. The user buffer must be four 
bytes longer than the record length to accommodate the RBN. 

(key) The label of your key area containing the key identifying 
the record to be retrieved and preceded by the lengths of 
the key and area. This area has the standard TEXT format 
and may be declared using the TEXT statement. If you do not 
use the TEXT statement for this field, you must code it in 
the same format as the TEXT statement generates. 
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The TEXT statement format is as folloNS^ 



Offset 



Field 



key - 2 LENGTH (1 byte) 

key - 1 KLEN (1 byte) 

key Key area ("LENGTH" bytes) 



c 



length The length of the key area. It must be equal to 
or greater than the full key length for the file 
in use. 

klen The actual length of the key in the key area to 
be used as the search argument for the 
operation. It must be less than or equal to the 
full length of the keys in the file in use. If 
klen is 0^ the full key length is assumed. 

A generic key search is performed Mhen klen is 
less than the full key size. The first n bytes 
(as specified by klen) of the key area are 
matched against the first n bytes of the keys in 
the file. The first matching key determines the 
record to be accessed. The full key of the 
record is returned in the key area. 

key area The area containing the key to be used as a 
search argument. If you are using a generic 
key» after a successful GET request this area 
contains the full key of the record accessed. 

(mode/krel) Retrieval type and key relational operator to be used. 
The folloNing are defined? 

EQ Retrieve only key equal 

GT Retrieve only key greater than 

GE Retrieve only key greater than or equal 

UPEQ Retrieve for update key equal 

UPGT Retrieve for update key greater than 

UPGE Retrieve for update key greater than or equal 
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GET Example 

The folloMing example gets a record uihose key is *JONES*. The file 
records are 80 bytes in length and the key length is 20 bytes. The 
record is returned in the area named RECORD* and because this is a GETR 
request* the RBN is also returned in the area named RBN» which must fol- 
low immediately after the record area. 



CALL JAM, ( GETR), FILEl, (RECORD), (KEY) 



FILEl 


DATA 


F»0' 


lACB ADDRESS 


KEY 


TEXT 


» JONES', LENGTH=20 


RECORD KEY 


RECORD 


DATA 


128F»0» 


RECORD AREA 


RBN 


DATA 


D'0» 


RBN 



FROM PROCESS 



GET Return codes 



Code 



Condi ti on 



-90 Request cancelled because the request was conditional and a 

wait on a lock or buffer would be required 
-58 Record not found 
-1 Successful 

7 Link module in use, synchronize use of link module with the 
program 

8 Load error for $IAM, verify $IAM exists and enough storage is 
available to load it 

10 Invalid request 

12 Data set shut down due to error; see Chapter 12, 
'Error Recovery* 

13 A required module is not included in $IAM 

22 Address supplied by your program is not a valid lACB 

100 Read error - check system return code 

101 Write error - check system return code 

200 Error occurred while accessing the primary file 
242 Secondary index is out of sync with primary file 

247 During auto-update processing a GETSEQ to a secondary file 
failed, auto-update processing continues 

248 I/O error on primary file during a secondary request 

249 GET UPDATE error occurred trying to update a bad RBN 
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GETS - GET BLOCK 



The GETB request retrieves a block of data from the indexed file and 
places the block in a user buffer area. The third parameter of the call 
points to the record in the block that matched the key search. The file 
must have been opened using the PROCESS request before the GETB request 
is i ssuedy and the process call must have specified block mode. 

The requested record is located by key. The search may be modified by a 
key relation (krel) or a key length (klen). The block containing the 
first record in the file that satisfies the key condition is the one 
that is retrieved. 

The block that is retrieved is locked to prevent other users from 
accessing it. The lock remains in place until another block is accessed 
or a DISCONN is issued. 

THE GETBC request performs the same function as the GETB, but it does 
not Mait for the locked block to become unlocked. If the block that it 
needs is locked, a code of -90 is returned. 

Syntax* 



label CALL lAM, (GETB IGETBC) , iacb, (recptr) , 

(key) , (model krel ) 

Required* iacb, recptr,key 
Defaults^ mode/krel=EQ 



^m. 



Operands Description 

iacb The label of a word containing the lACB address returned by 
PROCESS. 

(recptr) The label of a word that will contain the address of the 

record that satisfied the key condition. This is an address 
in the user buffer that contains the data block that was 
retri eved. 

(key) The label of your key area containing the key identifying 
the record to be retrieved and preceded by the lengths of 
the key area. This area has the standard TEXT format and 
may be declared using the TEXT statement. If you do not use 
the TEXT statement for this field, you must code it in the 
same format that the TEXT statement generates. 

The TEXT statement format is as follows^ 



Offset 



Field 



key - 2 LENGTH (1 byte) 

key - 1 KLEN (1 byte) 

key Key area ("LENGTH" bytes) 



© 



length The length of the key area. It must be equal to or 
greater than the full key length for the file in use. 

klen The actual length of the key in the key area to be 
used as the search argument for the operation. It 
must be less than or equal to the full length of the 
keys of the file in use. If klen is 0, the full key 
length is assumed. 

A generic key search is performed when klen is less 
than the full key size. The first n bytes (as speci- 
fied by klen) of the key area are matched against the 
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first n bytes of the keys in the file. The first 
matching key determines the record to be accessed. 
The full key of the record is returned in the key 
area. 

key area The area containing the key to be used as a 

search argument. If you are using a generic key, 
after a successful GET request this area contains the 
full key of the record accessed. 

(RIOde/krel) Retrieval type and the key relational operator to be used. 
The folloMing are defined^ 

EQ Retrieve only key equal 

GT Retrieve only key greater than 

GE Retrieve only key greater than or equal 

Note: Blocks may not be retrieved for update. 



o 
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GETB Example 

The folloNing example retrieves the data block that contains a record 
Mhose key is * JONES'. The file records are 80 bytes in length* the key 
length is 20 bytes and the block size is 512. A pointer to the record 
is returned in the area named RECP. The block is read into BLK» Mhich 
has been identified to $IAM as the block mode user buffer by a PROCESS 
request. 

Note: The buffer is specified on the PROCESS request. 



CALL 



FILEl DATA 

KEY TEXT 

RECP DATA 

BLK BUFFER 



JAM, (GETB), FILEl, (RECP), (KEY) 



F'O' 

' JONES', LENGTH=20 

F'O' 

548, BYTES 



lACB ADDRESS FROM PROCESS 

RECORD KEY 

ADDRESS OF RECORD IN DATA BLOCK 

BLOCK MODE BUFFER 

(BLKSIZE + 36 BYTES) 



GETB Return Codes 






Code 



Condi ti on 



-90 Request cancelled because the request Mas conditional 

Nait on a locked buffer Mould be required 
-58 Record not found 
-1 Successful 

7 Link module in use; synchronize use of link 
the program 

8 Load error for $IAM; verify $IAM exists and 
enough storage is available to load it 

10 Invalid request 

12 Data set closed due to error; see chapter 

13 A required module is not included in $IAM 
22 Address supplied by your program is not a 

100 Read error - check system return code 

101 Write error - check system return code 
200 Error occurred Mhile accessing the primary file 



and 



module Mith 
that 

11 

valid lACB 
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GETNB - GET NEXT BLOCK 



The GETNB request retrieves the next block of data from an indexed file 
and places it into a user buffer area. The file must be opened in block 
mode by the PROCESS request. 

If there is a locked block in the user buffer area Nhen the GETNB 
request is issued, the block logically following this block is read into 
the buffer area. If no block is in the user buffer area (for example* 
this is the first request after a PROCESS or another request has caused 
the current block to be unlocked) » then the first block of the file is 
read into the user buffer area. 

The block is locked to prevent other users from accessing it. The block 
remains in place until another block is read in or a DISCONN is issued. 

The GETNBC request performs the same function as GETNB but it does not 
Mait for a locked block to become unlocked. If the block that it needs 
is locked a code of -90 is returned. 

Syntax? 



label 



CALL lAM, (GETNB I GETNBC), iacb,(recptr),( key) 



Required** lACB, ( (recptr) , only if no previous GETB issued.) 
Defaults* None 



Operands Description 

iacb The label of a word containing the lACB address returned by 
PROCESS. 

(recptr) The label of a word that will contain the address of the 

record that satisfied the key condition. This is an address 
in the user buffer that contains the data block that was 
retri eved. 

(key) The label of your key area. GETNB uses the key area if it 
has to go to $IAM to get the first block in the file. The 
contents of the key area before the call are of no impoi — 
tance, and the contents afterwards should not be depended 
upon by the application. It is used only as a work area. 
This area has the standard TEXT format and may be declared 
using the TEXT statement. If you do not use the TEXT state- 
ment for this field, you must code it in the same format 
that the TEXT statement generates. 

The TEXT statement format is as follows? 



W 



Offset 



Field 



key - 2 LENGTH (1 byte) 

key - 1 KLEN (1 byte) 

key Key area ("LENGTH" bytes) 



length The length of the key area. It must be equal to or 
greater than the full key length for the file in use. 

klen Any positive value less than or equal to the length* 

key area The area containing the key to be used as a 

search argument* If you are using a generic key, 
after a successful GET request this area contains the 
full key of the record accessed. 
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GETNB Example 

The folloMing example gets the next block from the file. The file has a 
key length of 20. Upon return RECP Mill contain the address of the 
first record in the block. The PROCESS request specified block mode. 



CALL 



FILE DATA 
RECP DATA 
KEY TEXT 



lAM, (GETNB), FILE 



F»0« 
F'O' 
LENGTH=20 



lACB ADDRESS FROM PROCESS 
ADDRESS OF RECORD IN DATA BLOCK 
RECORD KEY 



GETNB Return Codes 






Code 



Condi ti on 



-90 Request cancelled because the request was conditional and a 

uiait on a lock or buffer would be required 
-80 End of data. 
-1 Successful 

7 Link module in use. Synchronize use of link module with 
the program. 

8 Load error for $IAM, verify $IAM exists and 
enough storage is available to load it. 

10 Invalid request. 

12 Data set shut down due to error; see chapter 12. 
regarding error recovery. 

13 A required module is not included in $IAM. 

22 Address supplied by your program is not a valid lACB. 

100 Read error - check system return code. 

101 Write error - check system return code. 

200 Error occurred while accessing the primary file 

Secondary index is out of sync with primary file. 
I/O error on primary file during a secondary request. 
GET UPDATE error occurred trying to update a bad RBN. 
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GETSEQ - GET RECORD (SEQUENTIAL HODE) 

The GETSEQ request retrieves a single record from the indexed file and 
places the record in a user area (buff). The file must be opened in the 
PROCESS mode. 

The first GETSEQ of a sequence is performed like a GET; the first record 
in the file that satisfies the key condition is the one that is 
retrieved. If key is zero, the first record in the file is retrieved. 
Subsequent requests in the sequence locate the next sequential record in 
the file and the key parameter is ignored if specified. The sequence is 
terminated by an end-of-data condition^ by an ENDSEQ> by a DISCONN» or 
by an error. During the sequence^ direct-access requests are invalid. 

Retrieval for update can be specified if the requested record is 
intended for possible modification or deletion. If update is used the 
record is locked and remains unavailable to any other requests until the 
update is completed by a PUTUP, PUTDE or RELEASE. The record is also 
released by ending the sequence with an ENDSEQ or by ending processing 
with a DISCONN or by an error. 

During an update, the user must not change the primary key field in the 
record or the field addressed by the primary key parameter. The Indexed 
Access Method checks for and prohibits key modification. 

The GETSEQC request retrieves a single record from the indexed file and 
places the record in a user area only if the record, block, or buffer is 
not locked. The file must be opened in the PROCESS mode. 

The GETSEQCR request retrieves the RBN of the specified record from the 
indexed file and places the record in a user area only if the record, 
block, or buffer is not locked. The file must be opened in the PROCESS 
mode. 

Note: Performance considerations regarding sequential processing can be 
found in "Other Performance Considerations" on page H--6. 

Syntax* 



label 



Requi red: 
Defaults: 



CALL lAM, (GETSEQ I GETSEQC I GETSEQR I GETSEQCR), iacb, 
(buff ), (key), (mode/krel) 

iacb, buff , key 
mode/krel =EQ 



Operand Description 

iacb The label of a Mord containing the IACB address returned by 
PROCESS. 

(buff) The label of the user area into uihich the requested record 
is placed. Uhen the RBN is requested, the RBN is returned 
at the end of the record. The user buffer must be four 
bytes longer than the record length to accommodate the RBN. 

(key) The label of the user key area containing the key identify- 
ing the record to be retrieved and preceded by the lengths 
of the key and area. If the first record of the file is to 
be retrieved, this field as specified should be 0. 



c 



^ 
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The key fields if specifiedf has the standard TEXT format 
and may be declared using the TEXT statement. If you do not 
use the TEXT statement for this fields you must code it in 
the same format as the TEXT statement generates. 

The TEXT statement format is as folloMS^ 



Offset 



Field 



key - 2 LENGTH (1 byte) 

key - 1 KLEN (1 byte) 

key Key area ("LENGTH" bytes) 






length The length of the key area. It must be equal to 
or greater than the full key length for the file 
in use. 

klen The actual length of the key in the key area to 
be used as the search argument for the 
operation. It must be less than or equal to the 
full length of the keys in the file in use. If 
klen is 0, the full key length is assumed. 

A generic key search is performed uihen klen is 
less than the full key size. The first n bytes 
(as specified by klen) of the key area are 
matched against the first n bytes of the keys in 
the file. The first matching key determines the 
record to be accessed. The full key of the 
record is returned in the key area. 

key area The area containing the key to be used as a 
search argument. If you are using a generic 
key* after the first successful GETSEQ request 
this area contains the full key of the record 
accessed. 

Retrieval type and key relational operator to be used. 
The following are defined? 

EQ Retrieve only key equal 

GT Retrieve only key greater than 

GE Retrieve only key greater than or equal 

UPEQ Retrieve for update key equal 

UPGT Retrieve for update key greater than 

UPGE Retrieve for update key greater than or equal 

After the first GETSEQ of a sequence only the retrieval type is meaning- 
ful. The keys are not checked for equal or greater than relationship. 



(mode/krel) 
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GETSEQ Example 



The folloMing example gets the record Mhose key is *KEY0001* and places 
it in an area called 'BUFFER*. The file is identified by the field 
named *FILE1*. Subsequent GETSEQ requests result in the next sequential 
record being returned. 



FILEl 

BUFFER 

KEY 



CALL I AM, (GETSEQ), FILEl, (BUFFER), (KEY) 



DATA F'O' lACB ADDRESS FROM PROCESS 

DATA 256F'0' I/O BUFFER 
TEXT •KEY0001',LENGTH=7 RECORD KEY 



GETSEQ Return Codes 



Code 



Condi tion 



-90 Request cancelled becau 
and a Mait on a lock or 
-80 End of data 
-58 Record not found 
-1 Successful 

7 Link module in use, syn 
module with the program 

8 Load error for $IAM, ve 
storage is available to 

10 Invalid request 

12 Data set shut down due 
'Error Recovery' 

13 A required module is no 
22 Address supplied by you 

100 Read error - check syst 

101 Write error - check sys 
200 Error occurred uhile ac 
242 Secondary index is out 

248 I/O error on primary fi 

249 GET UPDATE error occurr 



se the request was conditional 
buffer would be required 



chronize use of link 

rify $IAM exists and enough 
load it 

to error; see Chapter 12, 

t included in $IAM 

r program is not a valid lACB 

em return code 

tem return code 

cessing the primary file 

of sync with primary file. 

le during a secondary request, 

ed trying to update a bad RBN. 
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LOAD - OPEN FILE FOR RECORD LOADING 

The LOAD request builds an indexed access control block (lACB) associ- 
ated Mith the file specified by the DSCB parameter. The address 
returned in the iacb variable is the address used to connect requests 
under this LOAD to this file. 



To access the file by primary key» specify the primary file name as the 
DSCB parameter. On all subsequent requestst specify a primary key. 

To access the file by secondary key» specify the secondary file name as 
the DSCB parameter. On all subsequent requests, specify a secondary 
key. The Indexed Access Method automatically opens the primary file 
Mhen you specify a secondary file. 

Note: The directory must be set up to reflect the relationship among 
the primary file and any secondary files. 

LOAD opens the file for loading base records; the only acceptable proc- 
essing requests in this mode are PUT, EXTRACT and DISCONN. Only one 
user of a file can use the LOAD function at one time. 

If an error exit is specified, the error exit routine is executed when- 
ever any Indexed Access Method request under this LOAD terminates Mith a 
positive return code. 

Note: Return codes 1, 7, 8, and 22 are positive value return codes but 
they do not cause the error exit routine to be entered, even Mhen 
ERREXIT is coded. The negative (Marning) return codes also do not cause 
error exits. 






Syntax' 



label 

Requi red* 
Defaults^ 



CALL 



I AM, (LOAD), iacb, (dscb) , (open tab) , (mode) 



i acb , dscb, opentab 
mode=(SHARE) 



Operands Description 

iacb The label of a 1-Mord variable into Mhich the address of the 
indexed access control block (IACB) is returned. 

(dscb) The name of a valid DSCB. This name is DSn, Mhere n is a num- 
ber from 1-9, corresponding to a file defined by the PROGRAM 
statement. It can also be a name supplied by a DSCB state- 
ment. The CALL statement specifying LOAD causes the Indexed 
Access Method to open the index file in load mode. 
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(opentab) The label of a 3 Mord open table. The open table contains 

information used during this LOAD. The format of this table 
is as folloMs: 



Offset 



Field 



SYSRTCD 
ERREXIT 
(0) reserved 



Field Description 

SYSRTCD A 1-word variable into which the return code from 
any system function (such as READ and WRITE) is 
placed when requested under this LOAD by the 
Indexed Access Method. 

ERREXIT Your error exit routine address. If this address 
is zero, the error exit will not be taken. Note 
that error exits handle only positive return codes. 

Note: Return codes 1, It 8, and 22 Qr^^ positive 
return codes which do not cause the error exit rou- 
tine to be entered, even if ERREXIT is coded. 

RESERVED Must be for LOAD requests. 

(mode) Specifies shared or exclusive use of the file. 

SHARE Allows shared read/write access by PROCESS 
requests. 

ISHARE Allows shared read/write access by PROCESS requests 
with the independent processing flag on. 

The I prefix on SHARE mode prevents any automatic 
update functions on any associated secondary 
indexes, even if the auto-update flag is on in the 
directory entry for those associated secondary 
i ndexes. 

For a secondary index, the index is opened as an 
independent file and the records returned are sec- 
ondary index records, not user data records. 

EXCLUSV You can access the file in exclusive mode (EXCLUSV) 
only if there are no outstanding PROCESS or LOAD 
requests. No other user can access the file while 
exclusive use is in effect. 

lEXCLUSV You can access the file only if there are no out- 
standing PROCESS or LOAD requests. No other user 
can access the file while independent exclusive 
(lEXCLUSV) use is in effect. 

The I prefix on EXCLUSV mode prevents any automatic 
update functions on any associated secondary 
indexes, even if the auto-update flag is on in the 
directory entry for those associated secondary 
indexes. 

For a secondary index, the index is opened as SiX\ 
independent file and the records returned are sec- 
ondary index records, not user data records. 



o 
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LOAD Example 



The folloMing example opens the file identified by 'DS3» for record 
loading in exclusive mode. The field named *IACB* is set to the address 
of the lACB for this open. Subsequent requests use this field to refer 
to this file. The system return code is placed in the field named 
•OPEN'. An error opening the file results in the routine named 'ERROR' 
being executed. 



CALL IAM,(L0AD),IACB,(DS3),(0PEN),(EXCLUSV) 



lACB 


DATA 


F'O' 




OPEN 


DATA 


F'O' 


RETURN CODES 




DATA 


A 'ERROR' 


ERROR EXIT ROUTINE ADDRESS 




DATA 


F'O' 


NOT USED 
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LOAD Return codes 



Code 



Condi tion 



-79 Warning - File was opened and not closed during the 

last session. Normal processing continues 
-75 Warning - File has either not been formatted^ or the 

invalid indicator is on in the directory for that file 
-57 Data set has been loaded 
-1 Successful 

7 Link module in use» synchronize use of link 
module with the program 

8 Load error for $IAM, verify $IAM exists and enough 
storage is available to load it 

12 Data set shut down due to error; see Chapter 12, 
"Error Recovery' 

13 A required module is not included in $IAM 

14 Invalid index block found - during processing of an index 
block, an incorrect block type was found. 

17 JAM is inactive - not enough storage available. Use 
$IAMUT1 BF command to readjust storage size. 

23 Insufficient number of lACBs, use BF command of 
$IAMUT1 to allocate more 

50 File opened exclusively 

51 Data set already opened in load mode 

52 File in use, cannot open exclusively 

54 $IAM buffer too small to process a file with this block size 
Use the BF command of $IAMUT1 to increase the buffer size 

55 Insufficient FCBs 

56 Read error - FCB. Refer to system return code 

76 DSOPEN error occurred - The system error field in the 
open table contains the DSOPEN errors 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

77 Record save area not large enough - use $IAMUT1 BF 
command to set maximum record size for secondary 
index processing 

78 Attempted to open a secondary file for LOAD, file is not 
opened independently 

230 Directory READ error for $IAMDIR. Check system return code 

234 Directory error - DSNAME, VOL not found in $IAMDIR 

243 Primary file failed to open on a secondary OPEN request 
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PROCESS - OPEN FILE 






The PROCESS request builds an indexed access control block (lACB) asso- 
ciated with the file specified by the DSCB parameter. The address 
returned in the lACB variable is the address used to connect requests 
under this PROCESS to this file. 

To access the file by primary key» specify the primary file name as the 
DSCB parameter. On all subsequent requests^ specify a primary key. 

To access the file by secondary key, specify the secondary file name as 
the DSCB parameter. On all subsequent requests, specify a secondary 
key. The Indexed Access Method automatically opens the primary file 
Mhen you specify a secondary file. 

Either primary or secondary files may be accessed in block mode. Sec- 
ondary files, however, may be directly accessed in block mode only if 
they Mere opened as independent files. 

Note: The directory must be set up to reflect the relationship between 
the primary file and any secondary files. 

PROCESS opens the file for retrievals, updates, insertions, and 
deletions. Multiple users can PROCESS the same file. However, only one 
user at a time can use the LOAD function for a given file. 

If ERREXIT is specified, the error exit routine is executed whenever any 
Indexed Access Method request under this PROCESS terminates with a posi- 
tive return code. 

Note: Return codes 1, 7, 8, and 22 are positive value return 
codes but they do not cause the error exit routine to be entered, 
even when ERREXIT is coded. Also the negative (warning) return 
codes do not cause error exits. 

If EODEXIT is specified, the end-of-data exit routine is executed when- 
ever a GETSEQ associated with PROCESS attempts to access a record after 
the last record in the file. 



Syntax- 



label CALL lAM, (PROCESS) , iacb, (dscb) , (opentab) , (mode) 

Required: iacb, dscb, opentab 
Defaults: mode=(SHARE) 



Operands Description 

iacb The label of a 1-word variable into which the address of the 
indexed access control block (IACB) is returned. 

(dscb) The name of a valid DSCB. This name is DSn, where n is a num- 
ber from 1-9, corresponding to a file defined by the PRO- 
GRAM statement. It can also be a name supplied by a DSCB 
statement. The CALL statement specifying PROCESS causes the 
Indexed Access Method to open the index file in process mode. 
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(opentab) The label of a 3- or ^-word table that contains information 
used during this PROCESS request. If the mode does not spec- 
ify block mode» the format of this table is as follows^ 



Offset 



Field 



SYSRTCD 
ERREXIT 
EODEXIT 



If the mode does specify block mode> the format of the table 
is as folloMs: 



Offset 



Field 






SYSRTCD 


2 


ERREXIT 


4 


EODEXIT 


6 


UBUFFAD 



Field Description 

SYSRTCD A 1-word variable into which the return code from 
any system function (such as a READ or WRITE) is 
placed when requested under this PROCESS by the 
Indexed Access Method. 

ERREXIT Your error exit routine address. If this address 
is 0, the error will not be issued. Note that 
error exits handle only positive return codes. 

EODEXIT Your end~of-data exit routine address. If this 
address is 0> the end-of-data exit will not be 
used. 

UBUFFAD The address of the buffer area to be used in block 
I/O mode. This area has the standard BUFFER format 
and may be declared using the EDL BUFFER statement. 
If you do not use the BUFFER statement for this 
field, you must code it in the same format the 
BUFFER statement generates. The buffer statement 
format is as follows* 






Offset 



Field 



Buffer - 4 
Buffer - 1 
Buffer 



Zero 
LENGTH 
Buffer area 
Block size + 36 
("LENGTH" bytes) 



(mode) 



The buffer area must be at least the block size of 
the file plus 36 bytes in length. 

Specifies the shared or exclusive access to the file> and if 
it is being opened in block mode. 

SHARE Allows shared READ/klRITE access by multiple PROCESS 
or LOAD requests. 

SHAREB Same as SHARE» but open in block mode. 



\i,^ 



8-30 SC34-0771 



^^ 



o 



ISHARE AlloMS shared READ/URITE access by PROCESS requests 
Mith the independent processing flag on. 

The I prefix on share mode prevents any automatic 
update functions on any associated secondary 
indexes* even if the auto-update flag is on in the 
directory entry for those secondary indexes. 

For a secondary index* the index is opened as a 
secondary file* and the records returned are sec- 
ondary index records* not user data records. 

ISHAREB Same as ISHARE* but open in block mode. 

EXCLUSV The user can access the file only if there sre no 
outstanding PROCESS or LOAD requests. No other 
user can access the file uhile EXCLUSV (exclusive 
access) is in effect. 

EXCLUSB Same as EXCLUSV* but open in block mode. 

lEXCLUSV You can access the file only if there are no out- 
standing PROCESS or LOAD requests. No other user 
can access the file Mhi le lEXCLUSV (independent 
exclusive access) is in effect. 

The I prefix on EXCLUSV mode prevents any automatic 
update functions on any associated secondary 
indexes* even if the auto-update flag is on in the 
directory entry for those associated secondary 
i ndexes. 

For a secondary index* the index is opened as an 
independent file* and the records returned are sec- 
ondary index records* not user data records. 

lEXCLUSB Same as lEXCLUSV* but open in block mode. 
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PROCESS Example 



The folloMing example opens the file identified by 'DSl' for general 
access in shared access mode. The field named *IACB* is set to the 
address of the lACB for this open. Subsequent requests use this field 
to refer to this file. The system return code is placed in the field 
named 'OPENTAB*. An error opening the file results in the routine named 
'ERROR* being executed. An end-of-data condition on a subsequent 
request results in the transfer of control to the code at the label 
'END'. 



CALL IAM,CPR0CESS),IACB,(DS1),(0PENTAB),(SHARE) 



OPENTAB DATA F'O' 

DATA A( ERROR) 

DATA A(END) 

lACB DATA F'O' 



RETURN CODES 

ADDRESS OF ERROR EXIT ROUTINE 

ADDRESS OF EOD EXIT ROUTINE 



Block Hode PROCESS Example 



The following example opens a file identified as 'DS2' for general 
access in shared access block mode. The field named 'IACB2' is set to 
the address of the lACB for this file by $IAM during the execution of 
the PROCESS request. Subsequent requests use this field to refer to 
this file. The system return code is placed in the field '0PENTAB2'. 
In this example both the ERROR and END routine addresses are coded F'O' 
to indicate that no routines are supplied and control should return to 
the instruction following the call to lAM if an error or EOD condition 
occurs. These exits can be coded for block mode. The fourth entry under 
0PENTAB2 is the address of the buffer area to be used by $IAM. The 
buffer length must be at least the block size of the file plus 36. 








CALL 


lAM, 


(PR0CESS),IACB2,(DS2),(0PENTABZ),(SHAREB) 


0PENTAB2 


DATA 


F'O' 


RETURN CODES 




DATA 


F'O' 


NO ERROR EXIT ROUTINE 




DATA 


F'O' 


NO EOD EXIT ROUTINE 




DATA 


A(BUF) ADDRESS OF BLOCK I/O BUFFER | 


0PENTAB2 


DATA 


F'O' 


RETURN CODES 


IACB2 


DATA 


F'O' 




BUF 


BUFFER 


1060 


,bytes BLOCK SIZE + 36 



\y 
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PROCESS Return Codes 



Code 



Condi ti on 



g^^ 



-79 
-75 
-56 



-1 

7 



12 

13 
17 

23 

24 
25 
26 
50 
52 
5^ 

55 
56 
76 



77 



230 
234 
243 



klarning - File was opened and not closed during the 

last session. Normal processing continues 

Ularning - File has either not been formatted* or the 

invalid indicator is on in the directory for that file 

Your file has been opened in block mode, but it has 

auto-update secondaries. Do not issue PUTUP or PUTDE 

against it. 

Successful 

Link module in use» synchronize use of link 

module with the program 

Load error for $IAM, verify $IAM exists and enough 

storage is available to load it 

Data set shut down due to error; see Chapter 12, 

"Error Recovery* 

A required module is not included in $IAM 

lAM is inactive - not enough storage available. Use 

$IAMUT1 BF command to readjust storage size. 

Insufficient number of lACBs, use BF command of 

$IAMLIT1 to allocate more 

Invalid user buffer address 

Invalid user buffer length 

Invalid header information in block in user area. 

File opened exclusively 

File in use, cannot open exclusively 

$IAM buffer too small to process a file with this block size 

Use the BF command of $IAMUT1 to increase the buffer size 

Insufficient FCBs 

Read error - FCB. Refer to system return code 

DSOPEN error occurred - The system error field in the 

open table contains the DSOPEN error? 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

Record save area not large enough - use $IAMUT1 BF 

command ,to set maximum record size for secondary 

index processing 

Directory READ error for $IAMDIR. Check system return code 

Directory error - DSNAME, VOL not found in $IAMDIR 

Primary file failed to open on a secondary OPEN request 
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PUT - PUT RECORD INTO FILE 

The PUT request processes the record that is in your buffer (buff) 
according to the May the file Mas opened (LOAD or PROCESS). 

If the current open is for LOAD» the record must have a higher key than 
the highest key already in the file and only base record slots are used 
(refer to "Loading Base Records From An Application Program" on page 4-5 
for a description of load mode). If the current open is for PROCESS^ 
the record may have any key and is placed in key order in either a base 
record or in a free slot in the appropriate place in the file. 

The PUTC request requires a block lock. The request processes the 
record in your buffer (buff) according to the May the file Mas opened 
(LOAD or PROCESS). In order to obtain a block lock Mithout Maiting» 
there can be no other block lock or record locks in effect for the 
block. 

Syntax* 



label 



Requi red' 
Defaults! 



CALL 



all 
none 



IAM,(PUT|PUTC),iacb,(buff) 



Operands Description 



iacb The label of a Mord containing the lACB address returned by 
PROCESS or LOAD. 

(buff) The label of the user area containing the record to be added 
to the file. 



o 



V^' 
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o 



PUT Example 



The folloMing example puts the record in the area named 'BUFFER* into 
the file. The file is identified by the field named *FILE1'. 





CALL 


JAM, (PUT), FILEl, (BUFFER) 


FILEl 
BUFFER 


DATA 
DATA 


F'O* lACB ADDRESS RETURNED HERE 
256F'0' I/O BUFFER 



PUT Return codes 



o 



Code 



Condi tion 



-90 Request cancelled because the request was conditional 
and a wait on a lock or buffer uould be required 
-1 Successful 

7 Link module in use, synchronize use of link 
module Mith the program 

8 Load error for $IAM, verify $IAri exists and enough 
storage is available to load it 

10 Invalid request 

12 Data set shut down due to error; see Chapter 12, 
•Error Recovery' 

13 A required module is not included in $IAM 

14 Invalid index block found - during processing an 
incorrect index block type was found, recreate the file 

22 Address supplied by your program is not a valid lACB 

60 Out of sequence or duplicate key (LOAD mode only) 

61 End of file (in LOAD mode) 

62 Duplicate key found (PROCESS mode only) 
70 No space for insert; reorganize the file 

76 DSOPEN error occurred - The system error field in the 
OPEN table contains the DSOPEN error: 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

90 Internal key save area temporarily in use by another request 

100 Read error - check system return code 

101 Write error - check system return code 

230 Directory read error for $IAMDIR, Check system return code 
2^^ Error in opening auto-update on modification request 

246 Auto-update processing an INSERT to a secondary 

file failed, auto-update processing continues 
248 I/O error on primary file during a secondary request 



Chapter 8. Coding the Indexed Access Method Requests 8-35 



PUTDE - DELETE PREVIOUSLY READ RECORD 

The PUTDE request deletes a record from an indexed file. The record 
must have been previously retrieved by a GET or 6ETSEQ in update mode. 
Deleting the record creates free space in the file. The PUTDE releases 
the lock placed on the record by the GET or GETSEQ. 

The PUTDEC request deletes a record from an indexed file only if the 
block or buffer is not locked. 

Syntax ' 



label 


CALL 


lAM, (PUTDE 1 PUTDEC) , i acb, (buf f ) 


Requi red: 
Defaults: 


all 
none 





Operands Description 

iacb The label of a word containing the lACB address returned by 
PROCESS. 

(buff) The name of the area containing the record previously 
retrieved by GET or GETSEQ. 



PUTDE Example 

The following example deletes the record in the area named 'BUFFER' from 
the file. The record was read with either a GET or GETSEQ request in 
update mode. The file is identified by the field named 'FILEl'. 






CALL lAM, (PUTDE), FILEl, (BUFFER) 



FILEl 
BUFFER 



DATA F'O' 
DATA 256F'0» 



IACB ADDRESS FROM PROCESS 
I/O BUFFER 



Note: If you are processing primary $IAN files that have associated 
auto-update secondary indexes, do not issue a PUTDE in block mode. 
Issue a DELETE command instead. 



^k«i_ii'^ 
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PUTDE Return Codes 



c 



Code 



-90 

-85 

-1 

7 

8 

10 
12 

13 

1^ 

22 
27 

76 



85 
100 
101 
230 
242 

244 
245 

247 

248 



Condi tion 



Request cancelled because the request was conditional 

and a wait on a lock or buffer would be required 

Record not found 

Successful 

Link module in use^ synchronize use of link 

module with the program 

Load error for $IAM, verify $IAM exists and enough 

storage is available to load it 

Invalid request 

Data set shut down due to error; see Chapter IZt 

"Error Recovery' 

A required module is not included in $IAM 

Invalid index block found - during processing an incorrect 

index block was found. Recreate the file 

Address supplied by your program is not a valid lACB 

PUTDE is invalid against block mode files with 

auto-update secondary index files. 

DSOPEN error occurred - The system error field in the 

OPEN table contains the DSOPEN error: 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

Key was modified by user 

Read error - check system return code 

Write error - check system return code 

Directory read error for $IAMDIR. Check system return code 

Secondary index is out of sync with primary file. 

Must rebuild file to get back in sync. 

Error in opening auto-update on modification request 

Auto update PUTDE to a secondary file failedf 

auto-update processing continues. 

During auto-update processing a GETSEQ to a secondary 

file failed, auto-update processing continues. 

I/O error on primary file during a secondary request. 



Chapter 8. Coding the Indexed Access Method Requests 8-37 



PUTUP - UPDATE RECORD 



The PUTUP request replaces the record in the file with the record in 
your buffer. The record must have been retrieved by a GET or 6ETSEQ in 
update mode. You must not change the primary key field in the record or 
the contents of the key ar&a in your program returned by the GET or 
GETSEQ request. The Indexed Access Method checks for and prohibits pri- 
mary key modification. The PUTUP releases the lock placed on the record 
by the GET or GETSEQ. 

The PUTUPC request replaces the record in the file with the record in 
your buffer only if the records blocks or buffer is not locked. 



Syntax ? 



label 

Requi red: 
Defaults: 



CALL 

all 
none 



lAM, (PUTUP IPUTUPC), iacb, (buff ) 



Operands Description 



iacb 



The label of a word containing the IACB address returned by 
PROCESS. 



(buff) The label of the user area containing the record to replace 
the one previously retrieved. 



PUTUP Example 






The fol lowing example puts the updated record in the area named 'BUFFER' 
back into the file. The record was read with either a GET or GETSEQ 
request in update mode. The file is identified by the field named 
'FILEl'. 



CALL lAM, (PUTUP), FILEl, (BUFFER) 



FILEl DATA F»0» 
BUFFER DATA 256F»0' 



IACB ADDRESS FROM PROCESS 
I/O BUFFER 



Note: If you are processing primary $IAM files that have associated 
auto-update secondary indexes, do not issue a PUTUP in block mode. 
Issue a combination of DELETE and PUT requests to simulate the function. 



c 
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PUTUP Return codes 



o 



Code 



Condition 



-90 Request cancelled because the request Mas conditional 
and a Mait on a lock or buffer uould be required 
-1 Successful 

7 Link module in use» synchronize use of link 
module with the program 

8 Load error for $IAM, verify $IAri exists and enough 
storage is available to load it 

10 Invalid request 

12 Data set shut down due to error; see Chapter 12» 
'Error Recovery' 

13 A required module is not included in $IAM 

14 Invalid index block found - during processing an incorrect 
index block was found. Recreate the file 

22 Address supplied by your program is not a valid lACB 
27 PUTUP is invalid against block mode files with 

auto-update secondary index files. 
76 DSOPEN error occurred - The system error field in the 

OPEN table contains the DSOPEN error: 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

85 Key was modified by user 

100 Read error - check system return code 

101 Write error - check system return code 

230 Directory read error for $IAMDIR. Check system return code 
242 Secondary index is out of sync with primary file. 
Must rebuild file to get back in sync. 

244 Error in opening auto-update on modification request 

245 Auto update PUTDE to a secondary file failed^ 
auto-update processing continues. 

246 Auto-update processing an INSERT to a secondary file failed* 
auto-update processing continues 

247 During auto-update processing a 6ETSEQ to a secondary 
file failed* auto-update processing continues. 

248 I/O error on primary file during a secondary request. 



Chapter 8. Coding the Indexed Access Method Requests 8-39 



RELEASE - RELEASE RECORD 

The RELEASE request frees a record that has been locked by a GET or 
GETSEQ for update. A record lock is normally released by a PUTUP or 
PUTDE. The RELEASE request is useful for freeing the locked record Mhen 
the update need not be completed. RELEASE is valid only Mhen a record 
is locked for update. 



\J 



Syntax- 



label 



Requi red! 
Defaults: 



CALL 



all 
none 



JAM, (RELEASE), iacb 



Operands Description 

iacb The label of a Mord containing the IACB address returned by 
PROCESS. 



RELEASE Example 



The following example releases the record that uias read uiith either a 
GET or GETSEQ request in update mode. The file is identified by the 
field named 'FILE1». 



CALL JAM, (RELEASE), FILEl 



FILEl 



DATA F'0» 



IACB ADDRESS FROM PROCESS 



RELEASE Return Codes 



Code 


Condi ti on 


-1 


Successful 


7 


Link module in use, synchronize use of link 




module with the program 


8 


Load error for $IAM, verify $IAM exists and enough 




storage is available to load it 


10 


Invalid request 


12 


Data set shut down due to error; see Chapter 12, 




'Error Recovery* 


13 


A required module is not included in $IAM 


22 


Address supplied by your program is not a valid IACB 
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EDL CALL FUNCTIONS SYNTAX SUMMARY 



o 



FolloMing is a summary of the syntax of the EDL CALL instructions used 
to invoke the functions provided by the Indexed Access Method. 



label 


CALL 


JAM, 


label 


CALL 


JAM, 


label 


CALL 


JAM, 


label 


CALL 


JAM, 


label 


CALL 


JAM, 


label 


CALL 


JAM, 


label 


CALL 


lAM, 


label 


CALL 


JAM, 


label 


CALL 


lAM, 


label 


CALL 


JAM, 


label 


CALL 


lAM, 


label 


CALL 


lAM, 


label 


CALL 


JAM, 


label 


CALL 


lAM, 



( DELETE I DELETC) , iacb, (key) 

(DISCONN),iacb 

(ENDSEQ),iacb 

( EXTRACT) , i acb, (buff) , ( si ze) , ( type) 

( GET I GETC I GETR I GETCR ) , i acb, ( buff ) , ( key) , (mode/krel ) 

(GETSEQ|GETSEQC|6ETSEQCR|GETSEQR),iacb,(buff), 

(key) f (mode/krel) 

(GETB I GETBC) , iacb, (RECPTR) , (key) , (mode/krel ) 

(GETNB IGETNBC) , iacb, (RECPTR) , (key) 

(LOAD) , iacb, (dscb) , (open tab) , (mode) 

(PROCESS), iacb, (dscb), (opentab), (mode) 

(PUTlPUTC), iacb, (buff) 

(PUTDEJPUTDEC), iacb, (buff) 

(PUTUP|PUTUPC),iacb,(buff) 

(RELEASE), iacb 
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INDEXED ACCESS METHOD RETURN CODES SUMMARY 



Return 
Code 



-90 



85 
■80 
■79 

■75 



58 
■57 
56 



-1 
01 
07 

08 

10 
12 

13 
14 

17 

22 
23 

24 
25 
26 
27 

50 

51 
52 
54 

55 
56 
60 
61 
62 
70 



Condi ti on 



Request cancelled because the request was conditional 

and a wait on a lock or buffer would be required. 

Any locks obtained by this lACB were released. 

Record to be deleted not found 

End of data 

Warning - File was opened and not closed during 

the last session^ normal processing continues 

Warning - File has either not been formatted or 

the invalid indicator is on in the directory for 

that file 

Record not found 

Data set has been loaded 

Your file has been opened in block mode» but it has 

auto-update secondaries. Do not issue PUTUP or PUTDE 

against it. 

Successful completion 

Invalid function specified on CALL to $IAM 

Link module in use* synchronize use of link 

module with the program 

Load error for $IAM, verify $IAM exists and enough 

storage is available to load it 

Invalid request 

Data set shut down due to error; see Chapter 12, 

'Error Recovery* 

A required module is not included in $IAM 

Invalid index block found - during processing an 

incorrect index block type was found* recreate the file 

lAM is inactive ~ not enough storage available 

Use $IAriUTl BF command to readjust storage size 

Address supplied by your program is not a valid lACB 

Insufficient number of lACBs* use BF command of 

$IAMUT1 to allocate more 

Invalid user buffer address 

Invalid user buffer length 

Invalid header information in block in user area. 

PUTUP and PUTDE are invalid against block mode files 

with auto-update secondaries. 

Data set is opened for exclusive use» 

cannot be opened by another user 

Data set already opened in load mode 

Data set is opened* cannot be opened exclusively 

$IAM buffer too small to process a file with this block size 

Use the BF command of $IAMUT1 to increase the buffer size 

Get storage error - FCB 

READ error - FCB, refer to system return code 

Out of sequence or duplicate key in LOAD mode 

End of file in LOAD mode 

Duplicate key found in PROCESS mode 

No space for insert. Reorganize the file 
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Return 
Code 



Condition 



76 DSOPEN error occurred - The system error field in the 
OPEN table contains the DSOPEN error: 

21 - DSNAME, VOLUME not found 

22 - VOLSER error 

23 - I/O error 

77 Record save area not large enough - use $IAI1UT1 BF command 
to set maximum record size for secondary file processing 

78 Attempted to open a secondary file for LOAD, file is not 
opened independently 

80 FCB WRITE error during DELETE processing - see system 

return code 
85 Key field modified by user 
90 Internal key save area temporarily in use by another 

request 

100 READ error - check system return code 

101 WRITE error - check system return code 
110 WRITE error - data set closed 

120 Invalid EXTRACT type 

122 File does not contain FCB extension 

123 Cannot extract paging statistics. Data paging is not active 
150 Not enough storage available for data paging 

200 Error occurred Mhile accessing the primary file 

230 Directory read error for $IAMDIR 

231 $IAMQCB not found. Check sysgen for include of $IAMQCB 
234 Directory error - DSNAME,VOL not found in §IAMDIR 

242 Secondary index is out of sync with primary file. 
Must rebuild file to get back in sync. 

243 Primary file failed to open on secondary open request 

244 Error in opening an auto-update file on a modification 
request 

245 Auto-update PUTDE to a secondary file failed; auto-update 
processing continues 

246 Auto-update processing an INSERT to a secondary 
file failed, auto-update processing continues 

247 During auto-update processing a GETSEQ to a secondary 
file failed, auto-update processing continues 

248 I/O error on primary file during a secondary request 

249 GET UPDATE error occurred trying to update a bad RBN 



Note: For return codes 243 through 249, multiple errors may have 
occurred. Use $ILOG to display the errors. 
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CHAPTER 9. THE ^lAMUTl UTILITY 

This chapter describes hoM to use the $IAMUT1 utility to build and main- 
tain your indexed files. Each command is described* including its func- 
tion» parameters* and an example of hoM to use it. The file definition 
parameters or^t also described. 

This chapter is arranged in alphabetical order as follows: 

"BF — Tailor the Indexed Access Method Buffers" on page 9-4 

"DF — Define Indexed File" on page 9-6 

"DI — Display Parameter Values" on page 9-9 

"DR — Invoke Secondary Index Directory Functions" on page 9-10 

"EC — Control Echo Mode" on page 9-19 

"EF — Display Existing Indexed File Characteristics" on page 9-20 

"LO — Load Indexed File" on page 9-22 

"NP — Deactivate Paging" on page 9-25 

"PG — Select Paging" on page 9-26 

"PP — Define Paging Partitions" on page 9-27 

"PS — Get Paging Statistics" on page 9-28 

"RE — Reset Parameters" on page 9-29 

"RO — Reorganize Indexed File" on page 9-30 

"SE — ^^Set Parameters" on page 9-32 

"UN — Unload Indexed File" on page 9-41 



Chapter 9. The $IAMUT1 Utility 9-1 



$IAMUT1 



$IAI1UT1 can be invoked using the $L commands $JOBUTIL» or the Session 
Manager. $IAMUT1 functions use dynamic storage for work and buffer 
areas. The $IAMUT1 utility is shipped with sufficient dynamic storage 
to handle input and output block sizes of up to 512 bytes. This enables 
you to define an indexed file with a maximum block size of 512 bytes* 
and to loady unload, and reorganize indexed files Mith a maximum block 
size of 512 bytes. $IAMUT1 determines if enough dynamic storage has 
been provided. If sufficient storage has not been provided* $IANUT1 
displays a message. In order to handle large blocks of data» a larger 
dynamic storage area Mill have to be provided to $IAMLIT1. Additional 
dynamic storage can be provided by one of two Mays: provide the storage 
parameter on the $L command* or use the SS command of the $DISKUT2 util- 
ity. 

The load* unload and reorganize functions use the entire dynamic storage 
available to minimize the number of disk I/O operations. Improved pei — 
formance* therefore* can be obtained by specifying as large a dynamic 
area as possible. 

$IAriUTl updates data set $IAM Mhen it executes certain commands* such as 
PG* NP* PP* and BF. $IAMUT1 searches for data set $IAM in the following 
sequence: 

1. The volume from Mhich $IAMUT1 was loaded. 

2. The IPL volume. 

Uhen using these commands* $IAMUT1 updates the first occurrence of data 
set $IAM that it finds. 

§IAMUT1 updates directory data set $IAriDIR when it executes some direc- 
tory commands* such as AL* IE* DE* and UE. Directory data set $IAMDIR 
resides on the IPL volume. zf 
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The commands available under ^lAMUTl are listed below. To display this 
list at your terminal, enter a question mark in response to the prompt- 
ing message ENTER COmAND (?):. 

The command descriptions in this chapter are arranged in alphabetic 
order. 



ENTER COMMAND (?): ? 

EC - SET/RESET ECHO MODE 

EF - DISPLAY EXISTING FILE CHARACTERISTICS 
DR - SECONDARY INDEX DIRECTORY FUNCTIONS 
EN - END THE PROGRAM 

SE - SET DEFINE PARAMETERS 

DF - DEFINE AN INDEXED FILE 

DI - DISPLAY CURRENT SE PARAMETERS 

RE - RESET CURRENT VALUES FOR DEFINE 

LO - LOAD INDEXED FILE FROM SEQUENTIAL FILE 

RO - REORGANIZE INDEXED FILE 

UN - UNLOAD INDEXED FILE TO SEQUENTIAL FILE 

PG - SELECT DATA PAGING 
NP - DESELECT DATA PAGING 
PP - DEFINE PAGING PARTITIONS 
PS - DATA PAGING STATISTICS 
BF - SET BUFFER SIZES 

ENTER COMMAND (?): 



After the commands are displayed, you are again prompted with ENTER COM- 
MAND (?):. Respond with the command you wish to use. 
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BF— TAILOR THE INDEXED ACCESS METHOD BUFFERS 



The BF command specifies the amount of storage that the Indexed Access 
Method ($IAM) is to use for buffers and control blocks and the maximum 
record size for any file with a secondary index. 

BF prompts you for each of the following parameters by displaying the 
current value and accepting new settings. 



BUFFER SIZE 



Indicates the amount of storage (in bytes) to be 
used for the central buffer. Use the following 
formula to calculate your minimum buffer size* 



Buffer 


Size = (2 X blocksize) + (28 x blocksize/256) 


+ (n x 


blocksize) + (n x 28 x blocksize/256) 


where: 


blocksize = maximum block size 




n = maximum number of PUT operations (in LOAD 




mode) and GETSEQ operations that can be 




in effect at any point in time 



NUMBER OF lACBs Indicates the number of the lACBs. The maximum 

number of lACBs is 300. There is an lACB associ- 
ated with each PROCESS or LOAD that is issued. 
Ulhen calculating the number of lACBs you should 
consider the number of concurrent users you may 
have at any one time. 

Indicates the number of FCBs. The maximum number 
of FCBs is 6^. There is one FCB for evGry file 
that is open. Ulhen calculating the number of FCBs 
you should consider the maximum number files that 
might be open at a given time. 

Indicates the maximum record size of any file with 
an associated secondary index. If no files have a 
secondary index, this value can be zero. The 
actual amount of storage reserved as a result of 
this parameter is twice the value specified plus 8 
bytes. 

None of these take effect until the next time the Indexed Access Method 
is loaded. 



NUMBER OF FCBS 



MAXIMUM RECORD SIZE 



w 



9-4 SC34-0771 



BF 



BF Command Example 



This example sets the central buffer size to 5^0 bytes* leaves the num- 
ber of lACBs at 3» leaves the number of FCBs at 3, and sets the maximum 
record size of any file with a secondary index to 120 bytes. 



ENTER COMMAND (?): BF 






PARAMETER 


DEFAULT 


NEW VALUE 


BUFFER SIZE 




1080 


5<»0 


NUMBER OF lACBs 




3 




NUMBER OF FCBS 




3 




MAXIMUM RECORD SIZE 




256 


120 


VALUE(S) SET 








STORAGE FOR $IAM HAS 


BEEN 


SET TO 20A8 1 


BECOMES EFFECTIVE ON 


NEXT 


LOAD OF 


$IAM 


ENTER COMMAND (?): 









^'"V, 



Chapter 9. The $IAMUT1 Utility 9-5 



DF — DEFINE INDEXED FILE 



The DF command allocates^ defines* and formats an indexed file. The DF 
function will optionally invoke the load or reorganize function for you. 
Before entering DF» you must use the SE command to set up parameters 
that determine the size and format of the indexed file. The DF command 
uses those SE parameters to optionally allocate and format the file. 
The DF function can be invoked at the end of the SE function. 

The allocate step consists of using the file size computed during the SE 
step to dynamically allocate the file. If the file already exists^ the 
size is verified to ensure that it is large enough. The define step 
consists of writing the file control block (FCB) and its extension to 
the indexed file. Finally, the optional format step initializes all 
records in the indexed file to provide an empty structured file. 

INVOKING THE LOAD AND REORGANIZE FUNCTIONS FROM DF: You can invoke the 
LOAD or REORGANIZE functions directly from the DF (or SE) command. If 
you invoke these functions, DF does not format the file because LOAD and 
REORGANIZE will format the file. If you do not invoke the LOAD or REOR- 
GANIZE function, DF formats the file so you can load the file using an 
application program or the LO command. 

Notes: 



1. You can use the LOAD/REORGANIZE command later to load the file, if 
you do not invoke it from the DF command. 

2. An application program cannot access an unformatted indexed file. 

3. The prompt for the load/reorganize function occurs before the file 
is actually defined. 

^. A secondary index file cannot be loaded with the LO command, though 
it can be reorganized using the RO function. 



/4 \ 



Defining the File 

The define function prompts for the file to be allocated. If the file 
already exists, its size is checked. If the size is at least as large 
as needed, DF prompts you as to whether the file should be reused as 
fol lows'* 



ENTER COMMAND (?): DF 

ENTER DATA SET (NAME, VOLUME) 

DATA SET ALREADY EXISTS 

DELETE AND REALLOCATE (Y,N)? : Y 

DELETE AND REALLOCATE COMPLETED 



IANFILE,EDX003 



If the file exists, but it is not as large as needed, you have the 
option of deleting and reallocating it as shown in the following 
example: 



ENTER COMMAND (?): DF 

ENTER DATA SET (NAME, VOLUME) 

DATA SET ALREADY EXISTS 

DELETE AND REALLOCATE (Y,N)? : Y 

DELETE AND REALLOCATE COMPLETED 



MASTER, V0L123 
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If the file does not exist* it is allocated either uiith or without data 
set extents as follows: 



ENTER COMMAND (?): DF 

ENTER DATA SET (NAME, VOLUME) : MASTER, V0L123 

DYNAMIC DATA SET EXTENTS ON FILE (Y/N): Y 

SIZE OF DISK EXTENTS? 2 

NEW DATA SET IS ALLOCATED 



ENTER COMMAND (?): DF 

ENTER DATA SET (NAME, VOLUME) : MASTER, V0L123 
DYNAMIC DATA SET EXTENTS ON FILE (Y/N): N 
NEW DATA SET IS ALLOCATED 



Using Immediate Urite-Back 

DF prompts you to select whether or not you want to use the immediate 
write-back option. Immediate write-back has the same effect on primary 
or secondary indexed files. 

Each request to insert, delete, or update a data record causes the 
affected blocks to be read into the Indexed Access Method buffer. The 
actual modification to the block is performed in the buffer. 

If you enter N to the immediate write-back prompt, file modifications 
are held in the main storage buffer and not written back to the indexed 
file until the buffer space is needed for another block or until the 
file is closed. If the device where the file resides was powered off 
before the block was written back to the file, the modification to the 
file would not have been performed. 

If you enter Y to the immediate write-back prompt, you are assured that 
the changed block is written back to the file immediately. 

The prompt is as follows^ 



DO YOU WANT IMMEDIATE WRITE-BACK? Y 
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DF Command Example 

The fol lowing example shoMs a use of the DF command to define a file 
named MASTER on volume V0L123. Immediate Mrite-back is selected and the 
request to invoke LOAD or REORGANIZE is indicated. 



ENTER COMMAND (?): DF 

ENTER DATA SET (NAME, VOLUME) : MASTER* VOL 123 
DYNAMIC DATA SET EXTENTS ON FILE (Y/N): N 
NEW DATA SET IS ALLOCATED 
DO YOU WANT IMMEDIATE WRITE-BACK? Y 

INVOKE LOAD(L), REORGANIZE(R) OR END(E) AFTER CURRENT FUNCTION? 
DEFINE IN PROGRESS 

DATA SET SIZE IN EDX RECORDS: 17 

INDEXED ACCESS METHOD RETURN CODE: -1 
SYSTEM RETURN CODE: -1 

PROCEED WITH LOAD/REORGANIZE (Y/N) 
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DI — DISPLAY PARAMETER VALUES 

DI displays the current parameter values entered during the current ses- 
sion of $IAI1UT1 SE command. The parameter values can be used to format 
a file using the DF command or they can be modified by reusing the SE 
command. 

Note: You can also use the EF command to display the parameters of an 
exi sting f i le. 

The following example shoMS a use of the DI command. 



ENTER COMMAND (?): DI 

CURRENT VALUES FOR SE COMMAND ARE: 

FILE TYPE = PRIMARY 



BASEREC 


100 


BLKSIZE 


256 


RECSIZE 


80 


KEYSIZE 


28 


KEYPOS 


1 


FREEREC 


1 


FREEBLK 


10 


RSVBLK 


NULL 


RSVIX 





FPOOL 


NULL 


DELTHR 


NULL 


DYN 


NULL 






For a secondary file» the record size is not displayed. 
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DR — INVOKE SECONDARY INDEX DIRECTORY FUNCTIONS 

The DR command provides access to secondary index directory functions. 
Those functions are made available by replying DR when $IAMUT1 requests 
"ENTER COMMAND (?):". You can then respond to the "ENTER DIRECTORY COM- 
MAND (?):" with a subcommand. To obtain a list of the available subcom- 
mandSf reply with a question mark (?) as follows* 



ENTER COMMAND (?): DR 

ENTER DIRECTORY COMMAND (?)'• ? 

AL - ALLOCATE/REALLOCATE DIRECTORY 

LE - LIST ENTRIES 

IE - INSERT ENTRY 

DE - DELETE ENTRY 

UE - UPDATE ENTRY 

EN - END DIRECTORY FUNCTION 

ENTER DIRECTORY COMMAND (?): 



The directory function commands are arranged in alphabetical order as 
follows^ 

"AL — Allocate Directory" on page 9-11 

"DE — Delete Directory Entry" on page 9-12 

"EN — End Directory Function" on page 9-13 

"IE — Insert Entry" on page 9-14 

"LE — List Entries" on page 9-15 

"UE — Update Directory Entry" on page 9-17 



lf~^^ 



\j 
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AL — ALLOCATE DIRECTORY 



The AL subcommand allocates a directory for secondary indexes. If a 
directory already exists* this subcommand gives the option to delete and 
reallocate it. 

Note: To use this subcommand* you must first use the DR command. 

You are prompted to enter the maximum number of directory entries. 
Enter the number of entries you want the directory to be able to hold. 
Each entry describes a primary file or secondary index. The maximum 
number of entries defaults to ^7. 

The directory* $IAMDIR* is always allocated on the IPL volume. 

The following example shows a use of the AL subcommand to allocate a new 
directory with a capacity of 10 entries- 



ENTER DIRECTORY COMMAND (?): AL 

MAX t OF DIRECTORY ENTRIES: 10 

THE DIRECTORY DATA SET REQUIRES 1 EDX RECORDS* CONTINUE (Y/N/EN)? Y 

DIRECTORY DATA SET ALLOCATED: $IAMDIR* EDX002 



The next example assumes a directory already exists and allocates a new 
one. 



g Ik 



ENTER DIRECTORY COMMAND (?): AL 

DIRECTORY EXISTS* OPTIONS ARE: 

BN - BUILD NEW DIRECTORY 

AS - ADJUST SIZE 

EN - END DIRECTORY ALLOCATE 

ENTER OPTION: BN 

ALL DIRECTORY ENTRIES WILL BE DELETED* CONTINUE (Y/N)? Y 

MAX ff OF DIRECTORY ENTRIES: 20 

THE DIRECTORY DS REQUIRES 2 EDX RECORDS* CONTINUE (Y/N/EN) ? Y 

DIRECTORY DATA SET ALLOCATED: $IAMDIR* EDX002 



The following example* adjusts the size of the directory data set 
existing entries will be retained. 



All 



ENTER DIRECTORY COMMAND (?): AL 

DIRECTORY EXISTS* OPTIONS ARE: 

BN - BUILD NEW DIRECTORY 

AS - ADJUST SIZE 

EN - END DIRECTORY ALLOCATE 

ENTER OPTION: AS 

MAX « OF DIRECTORY ENTRIES: 1 

THE DIRECTORY DS REQUIRES 



1 EDX RECORDS, CONTINUE (Y/N/EN) ? Y 



DIRECTORY DATA SET ALLOCATED: $IAMDIR, EDX002 
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DE — DELETE DIRECTORY ENTRY 



The DE subcommand deletes an entry from the directory. If you delete a 
primary entry, all associated secondary index entries are also deleted. 

Note: To use this subcommand, you must first use the DR command. 

The following example shows the deletion of the directory entry for the 
file named MASTER on the volume named V0L123. MASTER is a primary index 
file entry which has secondary indexes associated with it. 



ENTER DIRECTORY COMMAND (?): DE 

ENTRY (DSNAME, VOLUME): MASTER, V0L123 

ASSOCIATED SECONDARY ENTRIES WILL BE DELETED, CONTINUE (Y/N)? 

DELETE SUCCESSFUL, NUMBER OF ENTRIES DELETED: 2 



The following example shows the deletion of the directory entry for a 
file named MASTER, on the volume named V0L123. MASTER is a primary 
index file entry which no longer has any secondary indexes associated 
wi th it. 



ENTER DIRECTORY COMMAND ( ? ) : DE 

ENTRY (DSNAME, VOLUME): MASTER 

ENTRY FOR MASTER ,EDX002 WILL BE DELETED, CONTINUE (Y/N)? Y 

DELETE SUCCESSFUL, NUMBER OF ENTRIES DELETED: 1 



4 ^ 
W 
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EN — END DIRECTORY FUNCTION 



The EN subcommand ends the directory functions (DR) and returns to 
$IAMUT1 for your next command. 
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IE — INSERT ENTRY 



XJ 



The IE subcommand inserts a new entry into the secondary index 
directory. It is used to insert either a primary or secondary entry. 
However, the primary entry must be inserted before any of its secondary 
entries can be inserted. 

For a primary entry, enter the data set name and volume of the file for 
which the entry is being inserted. Specify N when asked "IS THIS A SEC- 
ONDARY ENTRY (Y/N)?." 

For secondary entries, enter the data set name and volume of the second- 
ary index for which the entry is being inserted and specify that it is a 
secondary index. You are then prompted for additional information. 

Specify the name of the primary index file which the secondary index is 
to be associated with. You can select automatic update, which indicates 
that any change to a primary file is to be reflected in the secondary 
index. The default for automatic update is yes. 

The following example inserts a directory entry for a primary index 
file: 



ENTER DIRECTORY COMMAND (?): IE 
ENTRY (DSNAME, VOLUME).- TOMPRI,EDX002 
IS THIS A SECONDARY ENTRY (Y/N)? N 

DIRECTORY INSERT SUCCESSFUL 



The following example inserts a directory entry for a secondary index 
named ' TOMSECl ,EDX002'' which is to be associated with the primary index 
file *TOMPRI,EDX002' . Automatic update is selected. 



ENTER DIRECTORY COMMAND C?)i IE 
ENTRY (DSNAME, VOLUME) TOMSECl, EDX002 
IS THIS A SECONDARY ENTRY? Y 

ASSOCIATED PRIMARY ENTRY (DSNAME, VOLUME) : TOMPRI,EDX002 
AUTO-UPDATE (Y/N)? Y 



Notes To use this subcommand, you must first use the DR command. 
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LE — LIST ENTRIES 
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The LE subcommand lists the contents of one or more directory entries. 
Specify the name of a primary indexed file to get information about that 
file and its secondary indexes. Specify the name of a secondary index 
to get information about only that secondary index. To obtain a com- 
plete list of all information in the directory, just press the Enter Key 
Mithout supplying any data set name or volume. 

Note: To use this subcommand, you must first use the DR command. 

The following example lists the directory entries related to the primary 
file named 'TOMPRI' on volume »EDX002'. 



ENTER DIRECTORY COMMAND (?): LE 
ENTRY (DSMANE, VOLUME) BLANK=ALL: 


TOMPRI 




PRIMARY INDE- 
DSNAME VOLUME DATA SET PENDENT 


INVALID 


AUTO 
UPDATE 


TOMPRI EDX002 YES NO 
TOMSECl EDX002 NO NO 
T0MSEC2 EDX002 NO NO 


YES 
YES 


YES 
NO 


NUMBER OF DIRECTORY ENTRIES USED 
NUMBER OF AVAILABLE ENTRY SLOTS = 
DIRECTORY LIST COMPLETED 


= 5 
<»2 
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The folloMing example lists all directory entries. 



ENTER DIRECTORY COMMAND (?): LE 
ENTRY (DSNAME, VOLUME) BLANK=ALL: 






PRIMARY 
DSNAME VOLUME DATA SET 


INDE- 
PENDENT 


INVALID 


AUTO 
UPDATE 


EDXIAM EDX003 YES 
EDXIAMSl EDX0 03 NO 


NO 
NO 


}(XXX 
YES 


YES 


TOMPRI EDX002 YES 
TOMSECl EDX002 NO 
T0MSEC2 EDX002 NO 


NO 
NO 
NO 


YES 
YES 


YES 
NO 


NUMBER OF DIRECTORY ENTRIES USED = 
NUMBER OF AVAILABLE ENTRY SLOTS = 
DIRECTORY LIST COMPLETED 


5 
42 





l< 



9-1* SCS'i-O??! 



DR - UE 



UE — UPDATE DIRECTORY ENTRY 



The UE subcommand updates an entry in the secondary Index directory. 
You can use this command as follows^ 

• Specify null values for parameters to remain unchanged (press the 
Enter key kihen you are prompted for them). 

• Enter neM values for parameters to be modified. 

Note: You cannot change a primary entry to a secondary entry or a sec- 
ondary entry to a primary entry. To do this» you must delete the old 
entry and insert a neu one. 

The following example updates a primary directory entry named 
*MASTER,V0L123S changes the volume name from V0L123 to EDX002 and 
leaves the DSNAME MASTER as it is. 






ENTER DIRECTORY COMMAND (?): UE 

ENTRY (DSNAME, VOLUME) MASTER, V0L123 

THIS IS A PRIMARY ENTRY 

IN THE FOLLOWING, ENTER NEW VALUE OR, 
ENTER NULL LINE TO RETAIN (PRESENT VALUE) 

DSNAME (MASTER): 

VOLUME (V0L123): EDX002 

INDEPENDENT (N): 

DIRECTORY UPDATE SUCCESSFUL 
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The folloMing example updates a secondary directory entry named 
'MASTER, V0L123S changes the VOLUME name to EDX002 and leaves the DSNAME 
MASTER as it is. It sets automatic update, leaves the independent proc- 
essing flag as it is, and sets the invalid indicator off. 



ENTER DIRECTORY COMMAND (?): UE 

ENTRY (DSNAME, VOLUME) MASTER, V0L123 

THIS IS A SECONDARY ENTRY 

IN THE FOLLOWING, ENTER NEW VALUE OR, 

ENTER NULL LINE TO RETAIN (PRESENT VALUE) 

DSNAME (MASTER): 
VOLUME (EDX123): EDX002 
INDEPENDENT (N): 
INVALID INDICATOR (Y): N 
AUTO-UPDATE (Y): Y 

DIRECTORY UPDATE ENDED 



Note: To use this subcommand, you must first use the DR command. 



^J 
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EC 



EC enables you to enter or leave echo mode, bihen in echo modet all 
$IAMUT1 input and output is logged on the $SYSPRTR device. This enables 
you to save information about the files you maintain using $IAMUT1. 
Ulhen in echo mode, all input and output is logged until either the cur- 
rent utility session is ended or echo mode is reset by use of the EC 
command. Echo mode is off when $IAMUT1 is loaded. 

Note: Input and output from $DISKUT3 is not logged. 

The following examples show the commands to set and reset echo mode: 



ENTER COMMAND (?): EC 

DO YOU WANT ECHO MODE? (Y/N)?: 

FUNCTION COMPLETED 

ENTER COMMAND (?): EC 

DO YOU WANT ECHO MODE? (Y/N)?: 

FUNCTION COMPLETED 


Y 
N 


(Set echo mode) 
(Reset echo mode) 



f^ 
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EF — DISPLAY EXISTING INDEXED FILE CHARACTERISTICS 



The EF command displays the file definition parameters that Mere used to 
set up the file. The information is obtained from the FCB Extension 
block. This command does not give the size of the file in Event Driven 
Executive blocks. 



EF Command Example for Primary Files 

This example shows how to display the file parameters used to set up the 
file. 



ENTER COMMAND (?): EF 

EXHIBIT FUNCTION ACTIVE 

ENTER DATASET (NAME, VOLUME) : EDXIAM1,EDX003 



FILE TYPE 


= PRIMARY 


BASEREC 


20 


BLKSI2E 


256 


RECSIZE 


SO 


KEYSIZE 


4 


KEYPOS 


1 


FREEREC 





FREEBLK 





RSVBLK 


NULL 


RSVIX 





FPOOL 


NULL 


DELTHR 


NULL 


DYN 


10 



EXHIBIT FUNCTION COMPLETED 



o 
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EF Command Example for Secondary Files 

This example shoNS how to display the file parameters used to set up the 
file. 



ENTER COMMAND (?): EF 

EXHIBIT FUNCTION ACTIVE 

ENTER DATASET (NAME, VOLUME) : EDXIAM11,EDX003 



FILE TYPE = 


: SECONDARY 


BASEREC 


20 


BLKSIZE 


256 


KEYSIZE 


6 


KEYP05 


9 


FREEREC 





FREEBLK 





RSVBLK 


NULL 


RSVIX 





FPOOL 


NULL 


DELTNR 


NULL 


DYN 


10 






Note: If you create this secondary file with the SE option 1 com- 
mand, your secondary and primary file will look the same except 
for KEYSIZE and KEYP05. 
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LO — LOAD INDEXED FILE 



LO loads a primary indexed file from a sequential (blocked or unblocked) 
input file. (A secondary indexed file must be loaded by using the DF or 
SE command). A primary indexed file can be loaded in one of two envi- 
ronments. Loading an empty file is referred to as the initial load. 
For an indexed file that already contains some records* the LO command 
can be used to add records with higher keys (keys of higher value than 
those already in the indexed file). This is called load in extend envi- 
ronment. 

Blocks are read from the sequential file with the EDL READ instruction 
and de-blocking is performed, if necessary. In the initial load envi- 
ronment, data records are formatted into Indexed Access Method blocks 
and written to the indexed file with the EDL WRITE instruction. Corre- 
sponding index blocks are written as required. The remainder of the 
indexed file is formatted if formatting was not completed during the DF 
function. In the extend environment, records are loaded into the 
indexed file using Indexed Access Method PUT requests. 

The sequential input file can contain blocked or unblocked records. For 
a description of blocked and unblocked sequential data sets, see 
"Blocked and Unblocked Sequential Data Sets" on page 9-23. The records 
in the sequential file must be in ascending order by the data contained 
in the key field. If a record with a duplicate or out of sequence key 
is found, you are given the option to either omit the record and contin- 
ue loading, or to end loading. The indexed file must have been defined 
by using the SE and DF commands before using the LO command. 

Your response to the prompt message "ENTER INPUT BLOCKSIZE", defines to 

the LO command whether the input is a blocked or unblocked sequential 

file. A null response to the prompt "ENTER INPUT BLOCKSIZE" indicates ^f-\ 

an unblocked input file and the block size is then calculated using the L ] 

input record size value, rounded up to the next 256-byte multiple value. \ii^^ 

If the actual block size value is entered as your response to this 

prompt, a blocked sequential input file is indicated. 

The record lengths of the input and output files do not have to be the 
same. When the indexed file is opened, the record length is displayed 
on the terminal. At this point, you can specify the record length of 
the sequential file if it is different than that of the indexed file. 
If the indexed file records are longer than the sequential file records, 
the loaded records are left justified and filled with binary zeroes. If 
the indexed file records are shorter than the sequential file records, 
the following message appears on the terminal ^ 



INPUT REC GT OUTPUT REC. TRUNCATION WILL OCCUR 
OK TO PROCEED? 



Reply 'Y* to proceed (records will be truncated). 

Reply 'N* to terminate the load function. 

If the end of the input sequential file is reached, you can continue 
loading from another sequential file. You are asked if there is more 
data to load. If you reply yes (Y), you are prompted for the file and 
volume name of the new input sequential file to use. The load operation 
continues, putting the first record of the new input sequential file in 
the next available record slot of the indexed file. 

Note: The record lengths and block sizes of subsequent input files are 
assumed to be the same as the initial input file. 

If the end of input file is reached and you do not name another input 
file, the load operation is complete. 
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Note: If you are loading the indexed file from a tape file» $IAMUT1 
does not close the tape file upon completion of the load. Use the 
$VARYOFF command to close the tape file (refer to the Operator Commands 
and Utilities Reference in the EDX library for a description of the 
$VARYOFF command). 

The following example shouis use of the LO command' 



ENTER COMMAND (?)'• LO 

LOAD ACTIVE 

ENTER OUTPUT DATASET (NAME, VOLUME) : IAMFILE,EDX003 

$FSEDIT FILE RECSIZE = 128 

INPUT RECORD ASSUMED TO BE 80 BYTES. OK?: y 

ENTER INPUT BLOCKSIZE (NULL = UNBLOCKED): 

ENTER INPUT DATASET (NAME, VOLUME) : SEQ01,EDX003 

LOAD IN PROCESS 

END OF INPUT DATASET 

ANY MORE DATA TO BE LOADED?: n 

6 RECORDS LOADED 
LOAD SUCCESSFUL 



c 



Blocked and Unblocked Sequential Data Sets 

The LO (load) function of $IAMUT1 will accept either blocked or 
unblocked sequential data sets as input when loading an indexed file. 
The UN (unload) function will either block or unblock data as requested 
when unloading an indexed file to a sequential data set. 

UNBLOCKED SEQUENTIAL DATA SET: An unblocked sequential data set contains 
one record in each block. The blocksize must be a multiple of 256 
bytes. The record size must be equal or less than the block size. A 
block can span one or more EDX records. 

The following diagram illustrates the relationship of a data record of 
300 bytes to a block size of 512 bytes in an unblocked data set. 
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BLOCKED SEQUENTIAL DATA SET: In a blocked sequential data set a block 
can contain multiple logical records. The block size must be a multiple 
of 256 bytes. The record size must be equal to or less than the block 
size. A block can span one or more EDX records. 

The following diagram illustrates 6 data records of 80 bytes each within 
a block of 512 bytes in a blocked data set. 
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Both the blocked and unblocked forms of sequential data sets» used by 
the utility, are compatible with the language processors, Sort/Merge and 
data sets produced by $FSEDIT. If you use the EDX edit utilities to 
prepare your data records for input, remember that these utilities put 
one 80-byte line from $FSEDIT into a 128-byte $FSEDIT record. Two of 
these 128-byte records are then used to form one 256-byte EDX record. 
Ulhen you use such a data set as sequential input for the LO (load) func- 
tion, specify the record length as 128 and the block size as 256. If 
your indexed file is defined as having a record length of 80, you will 
receive the message "TRUNCATION WILL OCCUR." This is acceptable because 
Indexed Access Method strips off the extra bytes added by $FSEDIT. 

The last block of a blocked sequential data set may not have enough 
records for a full block. In this case, all of the unused space in the 
block is set to binary zeroes. 



Invoking the LOAD and REORGANIZE Functions 






You can invoke the LOAD or REORGANIZE functions directly from the DF 
command. If you invoke these functions, DF does not format the file 
because LOAD and REORGANIZE will do it. If you do not invoke the LOAD 
or REORGANIZE function, DF formats the file so you can load the file 
using an application program or $IAMUT1 at a later time. 

Notes: 

1. You can use the LOAD/REORGANIZE command later to load the file, if 
you do not invoke it from the DF command. 

2. An application program cannot access an unformatted indexed file. 

3. The prompt for the load/reorganize function occurs before the define 
step. 



9-24 SC34-0771 



KP 



NP — DEACTIVATE PAGING 



Tho NP command directs that data paging be doselected tho next time the 
Indexed Access Method is loaded. 

Page area sizes are not affected by this command. 



NP Command Example 



This example shoMS hoM to indicate data paging is to be deselected on 
the next invocation of the Indexed Access Method. 



ENTER COMMAND (?): NP 

DATA PAGING MARKED AS NOT ACTIVE 

BECOMES EFFECTIVE ON NEXT LOAD OF $IAM 






o 
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PG — SELECT PAGING 



The PG command directs that data paging be selected the next time the 
Indexed Access Method is loaded. 

Page area sizes ar& not affected by this command. 



PG Conmand Example 



This example shoMS hoM to indicate data paging is to be selected on the 
next invocation of the Indexed Access Method. 



ENTER COMMAND (?): PG 

DATA PAGING MARKED AS SELECTED 

BECOMES EFFECTIVE ON NEXT LOAD OF $IAM 

SEE INDEXED ACCESS METHOD GUIDE CONCERNING 

REMOVAL OF PAGING MODULES FROM STORAGE. 

ENTER COMMAND (?): 
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pp— DEFINE PAGING PARTITIONS 

The PP command defines the amount of storage in each partition that the 
Indexed Access Method should reserve for paging. Storage is actually 
used for paging only i*ihen paging is active. 

PP prompts you for the size of the paging area for each partition by 
displaying the partition number and current paging area size for that 
partition. Respond with a null entry (just press the Enter key) to 
retain that size. Enter a new size to change the space allocation. 
Sizes are displayed and entered in K bytes (IK = 1024) > and should be 
entered as even numbers (multiple of 2K). If not, they are adjusted up 
to the next even number. The new sizes do not take effect until the 
next time the Indexed Access Method is loaded with paging active. 



PP Command Example 



This example sets the paging area size in partition 3 to 40K and 
increases the paging area in partition 5 from 6K to lOK. 



o 



ENTER COMMAND (?): PP 




PARTITION 


CURRENT NEW 




1 


OK 






2 


OK 






3 


OK 


40 




<♦ 


OK 






5 


6K 


10 




6 


OK 






7 


OK 






8 


OK 






PAGE AREA SIZE(S) RESET 




BECOMES EFFECTIVE ON NEXT 


LOAD OF $IAM 


TOTAL PAGE 


AREA SIZE IS 


50K 


SEE INDEXED ACCESS METHOD 


GUIDE CONCERNING 


REMOVAL OF 


PAGING MODULES 


FROM STORAGE. 



Notes: 

1. The letter K is optional on input, and is assumed if missing. 

2. The new total page area size is 50K and becomes effective on the 
next LOAD of $IAM. 



Chapter 9. The $IAMUT1 Utility 9-27 



PS 



PS — GET PAGING STATISTICS 



The PS command displays data paging information about the currently exe- 
cuting Indexed Access Method. It shoMs "hit" information for reads* 
Mrites and overall. 



er 




After the statistics are displayed* you have the option of resetting th« 
counters to zero so that a new set of paging statistics can be gathered. 



PS Command Example 



Display the current paging statistics and reset them, 



ENTER COMMAND (?): PS 



FUNCTION 


HITS 


MISSES 


HIT X 


READ 


45678 


81205 


36 


WRITE 


2450 





100 


OVERALL 


48128 


81205 


37 



RESET STATISTICS (Y/N)? Y 
STATISTICS RESET 
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RE — RESET PARAMETERS 



RE resets the parameters set up by the SE command to their default val- 
ues. 

The folloMing example shoMS a use of the RE command: 



ENTER COMMAND (?): RE 
PARAMETERS RESET 
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RO— REORGANIZE INDEXED FILE 

RO reorganizes a primary or secondary indexed file. It unloads an 
indexed file filled by insert activity into an empty indexed file and 
reorganizes the records to provide space for additional inserts. 

This command requires two existing indexed files of the same type. Both 
the input file and the output file must be primary indexed files» or 
both must be secondary index files. Records are read sequentially from 
the input file using the Indexed Access Method GETSEQ request. The 
records are loaded into the output file in a manner similar to the ini- 
tial load of tPie LO command. 

All reserved and free space is retained as free space. 

Reorganizing a secondary index does not reset the secondary key sequence 
numbers during the reorgani zati on» because it does not use the primary 
file. The records are placed in another Indexed Access Method file 
without any modification within the individual records. 

The output indexed file must have been defined by using the SE or DF 
commands before using the RO command. The SE Option 3 will format an 
output file like the original file, or $VERIFY will show the number of 
records in the file so that you can set up an output file. 

The record lengths of the two files need not be the same. Unloaded 
records are truncated or filled with binary zeroes if record lengths 
differ (see LO command). The key fields and key positions of the two 
files must be the same; however, the other file specifications (SE 
parameters) may differ. 

INVOKING THE LOAD AND REORGANIZE FUNCTIONS FROM DF: You can invoke the 
LOAD or REORGANIZE functions directly from the DF command. If you 
invoke these functions, DF does not format the file because LOAD and 
REORGANIZE will do that, thus saving time. If you do not invoke the 
LOAD or REORGANIZE function, DF formats the file so you can load the 
file using an application program or the LO command. 

Notes: 

1. You can use the LOAD/REORGANIZE command later to load the file, if 
you do not invoke it from the DF command. 

2. An application program cannot access an unformatted indexed file. 

3. The prompt for the load/reorganize function occurs before the define 

step. 



/f 



J 
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The folloMing example shoMs use of the RO command* 



ENTER COMMAND (?): RO 

REORG ACTIVE 

ENTER INPUT DATASET (NAME, VOLUME) : IAMFILE>EDX003 
ENTER OUTPUT DATASET (NAME, VOLUME) : IAMFIL2,EDX003 
REORG IN PROCESS 

END OF INPUT DATASET 

100 RECORDS LOADED 
REORG SUCCESSFUL 

ENTER COMMAND (?): EN 



^kk«„^ 
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SE — SET PARAMETERS 



SE prompts you for parameters that determine the structure and size of 
the indexed file. An explanation of the SE command parameters follow 
and an example of each is included with the description. 

The parameter values entered are saved by $IAMUT1.^ This enables you to 
reuse the SE command to change one or more parameters without having to 
reenter all of them. The current values can be displayed by the DI com- 
mand. 

The SE command provides three methods of setting up an indexed file. 

Option 1 Significant Parameters — Enter a minimal set of SE parameters. 
The utility internally converts the smaller set to the com- 
plete set. 

Option 2 All Parameters — Enter the complete set of SE parameters. 

Option 3 Parameters from Existing Data Set — Use the set of SE parame- 
ters that were used previously to define an existing indexed 
file. 

Note: Information which is common to all three options appears near the 
end of the SE description under "All Options" on page 9-39. 

Uhen you specify the SE command, you are prompted to select one of the 
options as shown in the following display. 



SET FILE DEFINITION PARAMETERS 

= EXIT 

1 = SIGNIFICANT PARAMETERS 

2 = ALL PARAMETERS 

3 = PARAMETERS FROM EXISTING INDEXED DATASET 
ENTER OPTION: 



i 



J 



Option 1 

Option 1 prompts for a minimal set of parameters. It issues a prompt to 
determine if a secondary index is being defined. If so» the secondary 
file name, key size> and key position e^r^ requested. If a primary file 
is being defined, different prompts are issued. $IAMUT1 internally con- 
verts the option 1 parameters to option 2 parameters. 

Uhen the SE option 1 is invoked for the first time, the prompts and 
default values are as follows (sample values are shown for parameters 
that must be entered): 



SECONDARY INDEX (Y/N)?: N 




DEFAULT 


NEM VALUE 


RECORD SIZE 


80 


KEY SIZE 


<» 


KEY POSITION 1 




BLOCKING FACTOR (RECORDS PER BLOCK) 1 




NUMBER OF BASE RECORDS 


20 


ESTIMATED TOTAL RECORDS 24 




TYPE OF INSERT ACTIVITY(C=CLUSTERED,R=RANDOM) C 





o 
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On subsequent invocations of the SE option 1, the defaults are taken 
from the parameter values since the last SE option 1 invocation. Option 
1 and 3 values do not carry over to option Z, 

The estimated total records value defaults to the last value* provided 
this value equals or exceeds the current base records. Otherwise it 
defaults to 1.2 times the current base records. 

To set up a secondary index* enter the folloMing: 



SECONDARY INDEX (Y/N)?: Y 

ENTER SECONDARY DATASET NAME (DS,VOL): FILE01,EDX002 

SECONDARY KEY SIZE: 10 

SECONDARY KEY P0SITI0N:36 



Before you can define a secondary index* you must place an entry into 
the directory for the associated primary index file and the primary file 
must exist. The directory is searched to obtain the data set name and 
volume of the associated primary file which uiill then be used to compute 
the remainder of the secondary SE parameters. 



Parameter Descriptions for Option 1 

The attributes of the file are determined by the following SE command 
parameters: 

RECORD SIZE: The length* in bytes* of each record in the file. 

KEY SIZE: The length of the key to be used for this file. The minimum 
key length is 1. For primary files* the maximum key length is 254. 

KEY POSITION: The position* in bytes* of the key Mithin the record. The 
first byte of the record is position 1. 

BLOCKING FACTOR (RECORDS PER BLOCK): The total number of records to be 
placed in an Indexed Access Method block. This value and the record 
size Mill be used to compute the actual Indexed Access Method block 
size* rounded up to the next 256-byte value. The rounding up action may 
increase the actual blocking factor. 

NUMBER OF BASE RECORDS: The number of indexed record slots to be set up 
in the indexed file for LOAD mode. The number of base records must be 
greater than zero to alloM the file to load any data records. These 
record slots can be loaded with data records by $IAMUT1 or by a PUT 
request after either a LOAD or PROCESS request. 

ESTIMATED TOTAL RECORDS: The total number of records you expect the 
indexed file to contain after insert processing activity. 

TYPE OF INSERT ACTIVITY(C=CLUSTERED,R=RANDON) : Inserts are considered 
clustered if most of the inserts occur at only certain places in the 
file. The following diagram represents clustered inserts by vertically 
stacked bullets. 
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Inserts 
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The next diagram represents randomly inserted records. Inserts are con- 
sidered random if few or no points in the file have a concentration of 
activity; inserts are expected throughout the file. 









Blocks 
























Inserts 








SECONDARY KEY SIZE' The length* in bytes, of the secondary key within 
the primary record. For secondary keys the maximum key length is 250. 

SECONDARY KEY POSITION: The position, in bytes, of the secondary key 
within the primary record. 



Option 2 



G 



The following list shows the default values for parameters when the SE 
command is invoked the first time (all values are decimal): 



BASEREC 


NULL 


BLKSIZE 





RECSIZE 





KEYSIZE 





KEYPOS 


1 


FREEREC 





FREEBLK 





RSVBLK 


NULL 


RSVIX 





FPOOL 


NULL 


DELTHR 


NULL 


DYN 


NULL 



On subsequent invocations of the SE command, the option 2 defaults are 
taken from the parameter values set according to the last SE command, 
regardless of the option used. If the default value is acceptable, 
press the enter key when prompted for the parameter. If you wish to 
change the value for any parameter, enter the new value in response to 
the prompting message. 

The new value becomes the new default value for the current $IAMUT1 ses- 
sion. The parameters for which a null can be specified are BASEREC, 
FREEREC, FREEBLK, RSVBLK, RSVIX, FPOOL, DELTHR, and DYN. To specify a 
null parameter after the original default has been modified, enter an 
ampersand (&) in response to the prompting message. 



o 
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The following example shows a use of the SE command in establishing the 
size and structure of an indexed file. 



PARAMETER 


DEFAULT NEW VALUE 


BASEREC 


NULL 


100 


BLKSIZE 





256 


RECSIZE 





80 


KEYSIZE 





28 


KEYPOS 


1 


1 


FREEREC 





1 


FREEBLK 





10 


RSVBLK 


NULL 




RSVIX 







FPOOL 


NULL 




DELTHR 


NULL 




DYN 


NULL : 



Following the response to the DYN parameter, the following list is dis- 
played. The list shows the details of how the indexed file will be con- 
structed using the parameters just entered. 



D 



TOTAL LOGICAL RECORDS/DATA BLOCK 

FULL RECORDS/DATA BLOCK: 

INITIAL ALLOCATED DATA BLOCKS: 

INDEX ENTRY SIZE: 

TOTAL ENTRIES/INDEX BLOCK: 

FREE ENTRIES/PIXB: 

RESERVE ENTRIES/PIXBCBLOCKS): 

FULL ENTRIES/PIXB: 

RESERVE ENTRIES/SIXB: 

FULL ENTRIES/SIXB 

DELETE THRESHOLD ENTRIES: 

FREE POOL SIZE IN BLOCKS: 

« OF INDEX BLOCKS AT LEVEL 

« OF INDEX BLOCKS AT LEVEL 

« OF INDEX BLOCKS AT LEVEL 



l: 
2: 
3: 



DATA SET SIZE IN EDX RECORDS 



3 
2 

50 
32 
7 
1 

6 

7 
7 

9 
2 
1 

73 
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If a secondary file is being defined* the list of prompts is the same 
except for the following^ 

the reply to the prompt "SECONDARY INDEX (Y/N)?:" is Y 

the secondary data set name i s requested 

the RECSIZE prompt is omitted; the Indexed Access Method computes 
the correct record size 



SECONDARY INDEX (Y/N); Y 

ENTER SECONDARY DATASET (NAME, VOLUME) : 



Parameter Descriptions for Option 2 



The attributes of the file are determined by these SE command 
parameters^ 



BASEREC 



BLKSIZE 

RECSIZE 
KEYSIZE 

KEYPOS 
FREEREC 



FREEBLK 



The estimated number of records to be initially loaded into 
the file in ascending key sequence. These records can be 
loaded by $IAMUT1 or by a PUT request after either a LOAD or 
PROCESS request. 

The number of records must be greater than zero to alloN the 
file to load any data records. 

If DYN is not specified, BASEREC defaults to null, resulting 
in an error condition. In this case, specify BASEREC as a 
positive number. 

If DYN is specified, BASEREC defaults to one. 

The length, in bytes, of blocks in the file. It must be a 
multiple of 256. The Indexed Access Method uses 16 bytes in 
each block for a header. 

The length, in bytes, of each record in the file. Record 
length must not exceed block length minus 16. 

The length of the key to be used for this file. The minimum 
key length is 1. For primary files, the maximum key length is 
254. For a secondary index, the maximum key length is 250. 



The position, in byte-, of the key within the record, 
first byte of the record is position 1. 



The 



The number of free records to be reserved in each block. It 
must be less than the number of records p&r block (block size 
minus 16, divided by record size). If not, an error message 
is issued. The calculation is adjusted to ensure that there 
is at least one allocated record in the block; that is, there 
cannot be lOOJJ free records. 

FREEREC defaults to zero. 

The percentage (0-99) of each cluster to reserve for free 
blocks. The percentage calculation result is rounded up so 
that at least one free block results. The calculation is 
adjusted to ensure that there is at least one allocated block 
in the cluster; that is, there cannot be lOOJf free blocks. 

FREEBLK defaults to zero. 



^y 



^n..^'' 
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RSVBLK The percentage of the entries in each primary index block to 
reserve for cluster expansion. These reserved entries are 
used to point to neM data blocks as they are taken from the 
free pool to expand the cluster. The result of the calcu- 
lation is rounded up so that any non-zero specification indi- 
cates at least one reserved index entry. The calculation is 
adjusted to ensure that there is at least one allocated block 
in the cluster. 



RSVIX 






FPOOL 



Enter a null character (4) for this prompt if you do not uant 
initial reserved blocks and do not Nant the indexed access 
method to create reserved blocks as records are deleted and 
blocks become empty. Specify a value of zero for this prompt 
if you do not Mant initial reserved blocks but you do uiant the 
indexed access method to create reserved blocks as records are 
deleted and blocks become empty (See the DELTHR prompt). 

Note that the sum of the FREEBLK and RSVBLK prompts must be 
less than 100 or an error message is issued. This value 
defaults to null if the DYN parameter is not specified. If 
the DYN parameter is specified, this value defaults to zero. 

The percentage (0-99) of the entries in each second level 
index block to reserve for use in case of cluster splits. A 
cluster split is required ujhen there is no room to insert a 
new record in a cluster. Each cluster split uses one reserved 
entry of the second-level index block to create a new cluster 
with blocks from the free pool. The result of this calcu- 
lation is rounded up so that any non-zero specification 
indicates at least one reserved index entry. The calculation 
is adjusted so that there is at least one unreserved entry in 
each second level index block. This value defaults to zero. 

The percentage (0-100) of the maximum possible free pool to 
allocate as determined by the RSVIX and RSVBLK parameters. 
The RSVBLK and RSVIX prompts result in a file structure set up 
to draw on the free pool for expansion. 



If insertion 
file* every 
The number o 
unlikely con 
the file. I 
evenly distr 
are needed, 
evenness of 
large number 
evenly distr 
if insertion 
key ranges. 



activity is evenly dist 
reserve entry of every i 
f blocks drawn from the 
dition is the maximum fr 
n more realistic cases, 
ibuted throughout the fi 

The percentage specif ie 
the distribution of inse 

(90, for example) if yo 
ibuted. Specify a small 
s are anticipated to be 



r ibuted throughout the 
ndex block can be used, 
free pool to support this 
ee pool size needed for 
insertion activity is not 
le, so fewer free blocks 
d here represents the 
rted records. Specify a 
u expect insertions to be 
number (20, for example) 
concentrated in specific 



If a null character (Jt 
pool is not created fo 
parameter to override 
is specified, an empty 
be added to the free p 
become empty (see the 
not specify a null for 
null and/or the RSVIX 
returned. Conversely, 
FPOOL must not be null 



) is specified for this prompt, a free 
r this indexed file (you can use the DYN 
this and create a free pool). If zero 

free pool is created. Blocks can then 
ool as records are deleted and blocks 
DELTHR prompt explanation). If you do 

this prompt, the RSVBLK must not be 
must be non-zero or an error is 

if the RSVBLK and/or RSVIX is non-zero, 

or an error is returned. 



The default for FPOOL is a null; no free pool is created. 

DELTHR The percentage (0-99) of blocks to retain in the cluster as 

records are deleted and blocks made available. This is known 
as the delete threshold. Uhen a block becomes empty, it is 
first determined if the block should be given up to the free 
pool by checking the response to this prompt. If the block is 
not given up to the free pool, it is retained in the cluster^ 
either as a free block or as an active empty block. The 



Chapter 9. The $IAMUT1 Utility 9-37 



ra 



result of this calculation is rounded up so that any non-zero 

specification indicates at least one block. The calculation 

is adjusted to ensure that the cluster aluiays contains at 
least one block. 



o 



DYN 



If the DELTHR parameter is specified as null (&) and DYN is 
not specified/ DELTHR defaults to the number of allocated 
blocks in the cluster plus one half of the value calculated by 
the FREEBLK prompt. If the DELTHR parameter is specified as 
null and a value is specified for the DYN parameter, DELTHR 
defaults to zero. 

The number of blocks to be assigned to, or added to, the free 
pool. When DYN is used with other free pool parameters, the 
free pool size is calculated as specified by the FPOOL parame- 
ter plus the value specified for DYN, 

If DYN is specified without the FPOOL parameter, the free pool 
is the number of blocks specified for DYN. 

If DYN is specified, other parameters assume the following 
default values when specified as null: 



BASEREC 


_ 


1 


BLKSI2E 


= 





RECSI2E 


= 





KEYSIZE 


r 





KEYPOS 


= 


1 


FREEREC 


— 





FREEBLK 


= 





RSVBLK 


- 


NULL 


RSVIX 


- 





FPOOL 


- 


NULL 


DELTHR 


— 


NULL 



o 



When you specify the number of blocks for the DYN parameter, 
remember that the Indexed Access Method can store several data 
records in a block, depending on the record size and block 
size you specify. Each block contains a 16 byte header. The 
number of records that can be contained in each block can be 
calculated by the following formula? 



Records per block = (BLKSIZE-16 )/RECSIZE 



In the above calculation, use the integer quotient only; dis- 
card any remainder. 

Blocks can be taken from the free pool for use as index blocks 
as well as for data blocks, so provide some extra blocks for 
these. A reasonable estimate of the number of index blocks 
required is 10%. Thus, if you know the number of data records 
you would like to add to the file, you can calculate the num- 
ber of blocks to specify for the DYN parameter as follows? 



DYN = (Number of records to insert) x 1.1 
(Records per block) 



\y 
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option 3 



SE 



Option 3 issues a prompt to determine what existing file to obtain the 
parameters from. The parameters can be set exactly according to the 
parameters of the original file by replying Y to the appropriate prompt. 
OtherMise^ the parameters Mill be set based on the current condition of 
the existing data set to reflect insert activity. 



SECONDARY INDEX (Y/N)?: N 

NAME OF EXISTING INDEXED DATA SET (NAME, VOLUME) : IAHFILE»EDX003 

NEW PARAMETERS EXACTLY SAME AS ORIGINAL PARAMETERS (Y/N) ? Y 



DATA SETSIZE IN EDX RECORDS: 
INDEXED ACCESS METHOD RETURN CODE: 
SYSTEM RETURN CODE: 



17 
-1 
-1 



All Options 

For all three options, the prompts are followed by the option of enter- 
ing the DF (define file) function directly from the SE command. This 
simplifies the file definition process. The prompt is as follows: 



CREATE/DEFINE FILE (Y/N) ? Y 

DYNAMIC DATA SET EXTENTS ON FILE (Y/N): 
ENTER DATASET (NAME, VOLUME) : FILEOl ,EDX003 
NEW DATASET IS ALLOCATED 



N 



The immediate write-back option is then queried' 



DO YOU WANT IMMEDIATE WRITE-BACK? Y 
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The next prompt alloMS you the option of invoking the load or reorganize 
functions as follows^ 






INVOKE LOAD(L), REORGANIZE(R) OR END(E) AFTER CURRENT FUNCTION? L 
DEFINE IN PROGRESS 



Size calculations are performed using the parameter values you specify. 

After the values arQ entered^ the follouiing is displayed showing the 
size and structure of the defined indexed file. 



DATA SET SIZE IN EDX RECORDS: 
INDEXED ACCESS METHOD RETURN CODE: 
SYSTEM RETURN CODE: 

CREATE/DEFINE FILE (Y/N)?: 



17 
-1 
-1 



^ 



^t,^ 
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UN — UNLOAD INDEXED FILE 

UN unloads an indexed file to a sequential file. Records are read from 
the indexed file Mith the Indexed Access Method GETSEQ request and writ- 
ten into the sequential file with the EDL WRITE instruction. If a sec- 
ondary indexed file is specified^ the primary file will be unloaded in 
secondary key sequence. 

You can unload a secondary index independent of its primary if you first 
use the UE subcommand of the DR command of $IAMUT1 to set the independ- 
ent indicator. You must turn the independent indicator off when the 
unload operation is completed. 

The record lengths of the two files need not be the same. Unloaded 
records arQ truncated or padded with zeroes if the records lengths of 
the two data sets differ. For further detail » see the LO command. 

Records are placed into the sequential file in ascending key sequence as 
indicated by the indexed file. Unloaded records can be blocked or 
unblocked. For a description of blocked and unblocked data sets» see 
"Blocked and Unblocked Sequential Data Sets" on page 9-23. 

The UN command prompts you for the block size of the file to be 
unloaded. A null response or a value less than or equal to the record 
size causes the indexed file to be unloaded to an unblocked sequential 
file. The sequential file block size is calculated as the record size 
rounded up to the next 256-byte multiple value. If you want the file to 
be unloaded to a blocked sequential f i le^ specify the actual block size 
value to the prompt "OUTPUT BLOCK SIZE". The record and block sizes of 
subsequent output sequential files are assumed to be the same as the 
initial output sequential file. 

If the indexed file contains more records than are allocated in the 
sequential file» you are given the option to continue unloading to 
another sequential file. If you choose to continue unloading, you ar& 
prompted for the name of the file and volume to use to continue the 
unload operation. The unload operation continues, putting the records 
read from the indexed file into the new sequential file. If the end of 
the output file is reached and you choose not to continue, the unload 
operation ends. 

Note: Do not specify the same file for input and output. 
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UN 



The fol lowing example shoMS the use of the UN command to put 80-byte 
records into a blocked sequential file. 



o 



ENTER COMMAND (?): UN 

UNLOAD ACTIVE 

ENTER INPUT DATASET (NAME, VOLUME) : EDXF02,AH4VOL 
ENTER OUTPUT DATASET (NAME, VOLUME) : SEQ01,EDX003 
OUTPUT RECORD ASSUMED TO BE 80 BYTES. OK?: Y 
ENTER OUTPUT BLOCK SIZE (NULL = UNBLOCKED): 256 
UNLOAD IN PROCESS 

END OF INPUT DATASET 

100 RECORDS UNLOADED 
UNLOAD SUCCESSFUL 
ENTER COMMAND (?): EN 






^ku.^ 
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^lAMUTl COMPLETION CODES 



O 






Completi on 
Code 



-1 
7 
8 
12 
13 
23 
30 
31 

32 
3^ 
36 
37 
38 
39 
^0 

42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
54 
55 
56 
60 

61 
62 



Condi t i on 



Successful completion 

Link module in use 

Load error for $IAM 

Data set shut doun 

Module not included in load module $IAM 

Get storage error - lACB 

Inconsistent free space parameters uere specified. 

FCB WRITE error during IDEF processing, 

check system return code 

Blocksize not multiple of 256 

Data set is too small 



Inval 
Inval 
Inval 



d block size during file definition processing 
d record size 
d index size 



Record size greater than block size 

Invalid number of free records 

Invalid number of clusters 

Inval i d key si ze 

Invalid reserve index value 

Invalid reserve block value 

Invalid free pool value 

Invalid delete threshold value 

Invalid free block value 

Invalid number of base records 

Invalid key position 

Data set is already opened for exclusive use 

Data set opened in load mode 

Data set is opened, cannot be opened exclusively 

Invalid block size during PROCESS or LOAD 

Get storage for FCB error 

FCB READ error, check system return code 

LOAD mode key is equal to or less than previous 

high key in data set 

End of file in LOAD mode 

Duplicate key found in PROCESS mode 



Note: For completion codes number 30 and 37 through 49, check 
your parameters for consistency. 
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Completion 
Code 



100 
101 
110 
201 



210 

230 

231 

232 

233 
234 
235 
239 



Condi t ion 






READ error* chec 
WRITE error, che 
WRITE error - da 
Request failed b 
secondary could 
return code 
Request failed b 
loaded 

Directory read e 
directory exists 
$IAMQCB not foun 
of $IAMQCB 
Directory open e 
directory exists 
Directory relate 
Directory error 
Directory resour 
Directory write 
message 



k system return code 

ck system return code 

ta set closed 

ecause the primary file for this 

not be opened. Check system 

ecause $DISKUT3 could not be 

rror for $IAMDIR, verify that 

d, check sysgen for include 

rror for $IAMDIR, verify that 

d primary request is a primary entry 
- DSNAME,VOL not found in $IAMDIR 
ce has not been requested 
error. Refer to previously displayed 






^K..^ 
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o 



CHAPTER 10. THE ^VERIFY UTILITY 

$VERIFY checks the validity of an indexed file and prints control block 
and free space information about the file on a user-specified printer 
(such as $SYSPRTR). 

This $VERIFY description contains the following topics^ 

$VERIFY Functions 

Invoking $VERIFY 

$VERIFY Example 

$VERIFY Messages 

$VERIFY Storage Requirements. 



$VERIFY FUNCTIONS 






With $VERIFY you can'- 

• Verify that all pointers in an indexed file are valid and that the 
records are in ascending sequence by key. 

• Verify th^ contents of a secondary index against the primary file 
and report any discrepancies. 

• Print a formatted File Control Block (FOB) listing, including the 
FOB Extension block. The FCB Extension block contains the original 
file definition parameters. 

Note: The^FCB Extension block does not exist and file definition 
parameters are not saved in the FCB for indexed files defined prior 
to version 1.2 of the Indexed Access Method. The reorganize (RO) 
$IAMUT1 command can be used to reformat those files by adding an FCB 
Extension block to make use of all the $VERIFY facilities. 

• Print a report showing the distribution of free space in your file. 

• Determine if any space is available for inserts. 



o 
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INVOKING ^VERIFY 



$VERIFY can be invoked from either a terminal or a program coded in 
Event Driven Language. You supply the same input in either case. If 
you invoke $VERIFY from a terminal » supply the input required in 
response to prompts. If you invoke $VERIFY from a program* supply the 
input required as parameters passed to the program. 



o 



$VERIFY INPUT 



This section describes the input required to execute $VERIFY. 



output printer 



name* volume 



Option 



The name of a printer to which the report should 
be directed. The default printer is $SYSPRTR. 

Data set and volume names for the primary index 
file or secondary index to be processed. (Ensures 
that all chains within this data set are correct). 

The type of processing you want $VERIFY to do. 
The three options are' 



The FCB and the FCB Extension 
matted and printed. The file 
free space report is printed. 



blocks are for- 
is verified. A 



The FCB and the FCB Extension 
matted and printed. The file 
free space report is printed. 



blocks are for- 
is verified. No 



Cross verify option 



secnamey volume 



F The FCB and the FCB Extension blocks are foi — 
matted and printed. No free space report is 
printed, but the '# OF AVAILABLE BLOCKS IN 
FREEPOOL' entry can be examined to determine if 
space is available for inserts; if the value is 
greater than zero OO), space is available. 

The type of check you want $VERIFY to do between 
the primary index files and secondary indexes. 
The options are' 

Y a. If a primary index file was specified above 
as the data set name* this will check that all 
entries in the primary index file are in the 
secondary index. 

b. If a secondary index was specified above as 
the data set name* this will check that all 
entries in the secondary index are in the asso- 
ciated primary indexed file. 

N Do not perform any cross verification. 

Data set and volume names of the secondary index 
to be verified. Specify *ALL* to verify all sec- 
ondary indexes associated with the primary file. 









10-2 SC3*-0771 



INVOKING $VERIFY FRON A TERMINAL 



Load the $VERIFY program as follous^ 



> $L ^VERIFY 



Uhen $VERIFY begins execution^ you are prompted for the parameters 
described previously. A complete example of a $VERIFY invocation from a 
terminal is shoMn under "$VERIFY Example" on page 10-5. 



INVOKING $VERIFY FROM A PROGRAM 

$VERIFY can be invoked by EDL programs with the LOAD instruction. The 
only required parameter is the address of a 38-byte area that contains 



c 





Hex 


Length 


D 


i splacement 


(Bytes) 


Data set name 





8 


Volume name 


8 


6 


Detail listing request 


E 


1 


(Y, N, or F) 






Secondary file cross verify 


F 


1 


(Y or N) 






Secondary index file name 


10 


8 


Secondary index file volume 


18 


6 


Output Printer 


IE 


8 



The next example shouis the use of $VERIFY to verify a file named lAMFILE 

in the volume EDX002. A file verification and free space report are 

requested. The secondary file named SECIAM in the volume EDX002 is also 
veri f i ed. 
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EXAMPLE 


PROGRAM START 




START 


EQU 


H 






LOAD 


$VERIFY, PARMLIST 


,EVENT=VERIFY 




WAIT 


VERIFY 


WAIT FOR POST COMPLETE 




PROGSTOP 




PARMLIST 


EQU 


ii 




DSNAME 


DC 


CL8»IAMFILE' 


INDEXED DATA SET NAME 


VOLUME 


DC 


CL6»EDX002» 


VOLUME NAME 


DETAIL 


DC 


CL1»Y' 


PROCESSING OPTION 


SECONDRY 


DC 


CLl'Y' 


SECONDARY FILE VERIFICATION 


SECDSN 


DC 


CL8'SECIAM» 


SECONDARY FILE NAME 


SECVOL 


DC 


CL6'EDX002» 


SECONDARY FILE VOLUME 


PRINTER 


DC 


CL8'$SYSPRTR» 


OUTPUT PRINTER 


xNOTE: BLANKS 


CAUSE DEFAULT TO 


$SYSPRTR 


VERIFY 


ECB 


-1 


EVENT CONTROL BLOCK 




ENDPROG 






END 







o 
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^VERIFY EXAMPLE 



This section presents the input and output for an example run of 
$VERIFY, along with descriptions of the material presented. 

$VERIFY is invoked from the terminal as follows- 



[13 
[23 

[3] 

[41 

[53 

[61 

C7] 

t8] 



> $L $VERIFY 

INDEXED ACCESS METHOD FILE VERIFICATION PROGRAM ACTIVE 

ENTER NAME OF OUTPUT PRINTER. (BLANK = $SYSPRTR): 

(NAME, VOLUME): DPRIMl,EDXIAM 

DO YOU WANT DETAIL LISTING? (Y/N/F/?)?: Y 

DO YOU WISH TO VERIFY SECONDARY VS PRIMARY INDEXES (Y/N):N 

VERIFICATION COMPLETE, ERROR(S) ENCOUNTERED 

$VERIFY ENDED 



c 



[11 In this example, the first line loads and executes $VERIFY. 

[2] The second line is printed by the program to indicate that execution 
has begun. 

[3] This line allows you to direct the output to a particular printer. 
You can also press the Enter key without supplying a device name and the 
output will be printed on $SY5PRTR. 

[4] In the fourth line, the program prompts for the data set name and 
volume of the indexed file to be referenced by the program. In this 
example the reply indicates that the data set is DPRIMl, located on vol- 
ume EDXIAM. 

[53 In the fifth line, the program prompts for the amount of detail to 
be provided as output. The response of Y indicates that maximum detail 
is to be provided. 

163 In the sixth line, the program prompts for verification of secondary 
indexes. The response of N indicates that secondary indexes are not to 
be verified. As the program executes, it provides output to the 
printer, as shown in the example outputs that follow. 

[73 Finally, messages are displayed to indicate the number of errors 
found. 

[83 This information message is provided stating that the program has 
ended. 
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FCB REPORT 



The first page of the example output from $VERIFY follows, 
always printed. 



This page is 



VERIFY REPORT. FILE = DPRIMl , VOLUME = EDXIAM 

FLAGl : FILE FILE 
LOADED TYPE 

Y 1 (0=PRPQ, 1=PP) 

KEY SIZE = 6 

KEY POSITION = 1 

BLOCK SIZE = 256 

RECORD SIZE = 60 

INDEX ENTRY SIZE = 10 

RBN OF HIGH LEVEL INDEX BLOCK IN USE = 2 

RBN OF LAST DATA BLOCK IN USE = 786 

RBN OF FIRST DATA BLOCK IN USE = 6 

TOTAL RECORDS PER DATA BLOCK = 4 

TOTAL ENTRIES PER INDEX BLOCK = 2^ 

LOAD POINT VALUE FOR A DATA BLOCK = 4 

LOAD POINT VALUE FOR AN INDEX BLOCK = 24 

FLA62 ' IMMEDIATE SECONDARY FILE 

WRITE-BACK INDEX FILE FORMATTED 
N NY 

VERSION NUMBER = 2.0 

DELETE THRESHOLD (RECORDS) = 

« OF AVAILABLE BLOCKS IN FREEPOOL 30 

RBN OF 1ST FREE POOL BLOCK = 787 

RBN OF HIGHEST LOGICAL INDEX BLOCK = 2 

LEVEL OF HIGHEST INDEX BLOCK IN USE= 3 

CURRENT NO. OF RECORDS IN FILE = 3000 



The preceding sample report is interpreted as follows^ 

The first line shows the data set name and volume. 

FLAGll These three lines show the significant bits of the first flag 
byte in the FCB. The first two of the three lines are a heading. 
The third line shows the bit value (1 = on and ~ off or Y = on and 
N = off). The headings are defined as follows* 

FILE LOADED" Data set has been loaded flag. This flag is set when 
any record has been successfully loaded into the file 
in load mode. 

FILE TYPE? This flag indicates whether the indexed file was cre- 
ated with the Realtime Programming System Indexed 
Access Method PRPQ (bit=0) or either the Event Driven 
Executive or Realtime Programming System Indexed Access 
Method Program Product (bit=l). 

KEY SIZE: Shows the size of the key in bytes. 

KEY POSITION: Shows the byte di splacement of the key from the start of 
the record. 



BLOCK size: 
RECORD size: 



Shows the byte length of blocks in the file. 
Shows the byte length of records in the file. 



o 
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^*\ 






INDEX ENTRY SIZE: Shouis the number of bytes in each index entry. This 
length should be the key length plus ^, rounded up to a multiple of 
two bytes, 

RBN OF HIGH LEVEL INDEX BLOCK IN USE: ShoMS which index block is to be 
used as the starting point when the index is to be searched. 

RBN OF LAST DATA BLOCK IN USE: Points to the last logical data block 
in the file which has been used. 

RBN OF FIRST DATA BLOCK IN USE: Points to the first logical data block 
in the file which has been used. It is used as the starting point 
when a sequential read operation is begun with no key specified. 

TOTAL RECORDS PER DATA BLOCK: Shows how many data records can be con- 
tained in a data block. 

TOTAL ENTRIES PER INDEX BLOCK: Shows how many index entries can be 
contained in an index block. 

LOAD POINT VALUE FOR A DATA BLOCK: The number of records that can be 
placed in each data block while in load mode. This value is calcu- 
lated at file definition time to provide the requested number of free 
records. 

LOAD POINT VALUE FOR AN INDEX BLOCK: The number of data blocks in each 
cluster to be used while in load mode. This value is calculated at 
file definition time to provide the space requested by the RSVBLK» 
RSVIX and FREEBLK parameters. 

FLAG2: Another byte of flags described by a pair of lines: a heading 
line followed by a data line. The heading has the following meaning: 

IMMEDIATE WRITE-BACK: Immediate write back flag. If set (Y), this 

flag indicates that the immediate write back 
option was specified when the indexed file was 
def i ned. 

SECONDARY INDEX FILE: A Y indicates that this is a secondary file. 

N indicates that this is a primary file. 

FILE formatted: Y indicates that the file has been formatted. 

N indicates that only the parameters have 
been specified and the file allocated. The 
file has not been formatted. 

VERSION number: Shows the version number and modification level of the 
Indexed Access Method that was used to define the indexed file. 

DELETE THRESHHOLD (RECORDS): Indicates the number of data blocks to 
retain in each cluster as records sre deleted and blocks become 
empty. This value is calculated when the file is defined and is based 
on the DELTHR parameter. 

« OF AVAILABLE BLOCKS IN FREEPOOL: The number of available blocks in 
the free pool. This count is updated as blocks are taken from or 
returned to the free pool. 
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RBN OF 1ST FREE POOL BLOCK: Points to the last block which was put in 
the free pool (which is the next block to be taken from the free 
pool) . 

RBN OF HIGHEST LOGICAL INDEX BLOCK: Points to the logical top of the 
index. In some cases (if the file has not been completely loaded), 
this RBN might not agree with the RBN OF HIGHEST LEVEL INDEX BLOCK IN 
USE. If it does not agree, then the file is structured with index 
blocks that are not yet needed because the file does not contain 
enough records. 



LEVEL OF HIGHEST INDEX BLOCK IN USE: 
index are currently in use. 



CURRENT NO. OF RECORDS IN FILE: 
now contained in the file. 



Indicates how many levels of the 
The current number of records that are 



FCB EXTENSION REPORT 



The second page of the example output from $VERIFY follows. This page 
is always printed. 

This information is obtained from the FCB Extension block and shows the 
parameters that were specified when the file was defined. Some informa- 
tion (BLKSIZE, RECSI2E, KEYSIZE, KEYPOS) is duplicated on the FCB and 
FCB Extension report because it is contained in both control blocks. 
The values should correspond with each other. The word NULL for the 
value of a parameter indicates that no value was specified when the file 
was defined. 



VERIFY REPORT. 


FILE = DPRIMl , VOLUME = 


EDXIAM 


INDEX FILE 


DEFINED WITH 


THESE PARAMETERS: 




BASEREC= 




3000 






BLKSIZE= 




256 






RECSIZE= 




60 


, ^v 




KEYSIZE= 




6 






KEYPOS= 




1 






FREEREC= 











FREEBLK= 











RSVBLK= 




NULL 






RSVIX= 











FPOOL= 




NULL 






DELTHR= 




NULL 






DYN = 




30 










Note: The parameters are the file definition parameters that were spec- 
ified using the SE command of the $IAMUT1 utility when the file was 
def i ned. 



O 
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FREE SPACE REPORT 






The folloNing is a free space report of the example output from $VERIFY. 
The free space report is printed only if the $VERIFY option is specified 
as Y. 






VERIFY 


REPORT. FILE = XMPLl , 


VOLUME = 


EDX002 










TOTAL 


USED 


UNUSED 


RESERVE 


FREE 


AVAILABLE 


HIGH KEY 


RBN LVL 


ENTRIES 


ENTRIES 


ENTRIES ENTRIES 


BLOCKS 


RECORD SLOTS 


(FIRST 


















20 CHAR.) 


2 


3 


24 


2 





22 





— 


143949 


3 


2 


24 


24 





16 





— 


130536 


^ 


2 


24 


8 





16 





-- 


143949 


5 




24 


24 














044932 


30 




24 


24 














046750 


55 




24 


24 














048655 


80 




24 


24 














050527 


105 




24 


24 














052392 


130 




24 


24 














054225 


155 




24 


24 














056075 


180 




24 


24 














057930 


205 




24 


24 














059829 


230 




24 


24 














061640 


255 




24 


24 














063548 


280 




24 


24 














065389 


305 




24 


24 














067297 


330 




24 


24 














069166 


355 




24 


24 














071029 


380 




24 


24 














072887 


^05 




24 


24 














074731 


430 




24 


24 














076586 


<f55 




24 


24 














078441 


480 




24 


24 














080329 


505 




24 


24 














082175 


530 




24 


24 














084006 


555 




24 


24 














085861 


580 




24 


24 














130536 


605 




24 


24 














132395 


630 




24 


24 














134205 


655 




24 


24 














136097 


680 




24 


24 














137929 


705 




24 


24 














139815 


730 




24 


24 














141655 


755 




24 


24 














143523 


780 




24 


6 





18 








143949 


VERIFICATION COMPLETE, 





ERROR(S) 


ENCOUNTERED 
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In this report, each printed line represents an index block. The col- 
umns have the folloMing meanings: 

RBN: The relative block number uiithin the indexed filet based on the 
block size specified Mhen the file Mas defined. The first block 
in the file is relative block number zero. 

LVL5 The level of the index block analyzed. LoMest level (PIXB) is 1» 
second level (SIXB) is 2, etc. 

TOTAL ENTRIES: The maximum number of index entries that can fit in an 
index block. 

USED entries: The number of entries used in this index block. 

UNUSED entries: The number of entries in the index block which are 
neither used nor reserved. 

RESERVE entries: The number of reserve entries in this index block. 

This number represents the number of new index blocks that can be 
obtained from the free pool for creation of new blocks^ provided 
there are enough blocks remaining in the free pool. 

FREE blocks: The number of free blocks associated with this index 
block. 

AVAILABLE RECORD SLOTS: The maximum number of records that can be 

inserted into this cluster without obtaining blocks from the free 
pool . 

HIGHEST KEY IN BLOCK: The first 20 bytes of the highest key in the 
block. 



o 
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^VERIFY MESSAGES 



As $VERIFY executes* any errors encountered result in an error message 
being written describing the type of error and where the error occurred. 



FILE ERROR MESSAGES 



The following messages indicate that the indexed file contains errors^ 



o 



t BLOCKS IN FREEPOOL CHAIN DOES NOT MATCH FREE POOL COUNT IN FCB . 

BLOCK OUT OF SEQUENCE. RBN . 

HIGH KEY IN RBN ^ DOES NOT MATCH INDEX ENTRY IN RBN . 

POINTERS IN HEADER OF HIGH INDEX BLOCK ARE NOT ZERO. 

RBN CONTAINS INVALID UPWARD POINTER. 

RBN CONTAINS INVALID BACKWARD POINTER. 

RBN CONTAINS INVALID FORWARD POINTER. 

RBN IS IN FREEPOOL CHAIN, BUT IS NOT A VALID FREEPOOL BLOCK. 

RECORD OUT OF SEQUENCE NEAR RBN _. 



RECORD MATCH NOT FOUND FOR SEC INDEX. 

PRIMARY= 

SECONDARY= 



If any of these messages are printed, the indexed file has at least one 
error. 

Possible sources of the error include? 

• The data set is not an indexed file. 

• Data in the file has been inadvertently destroyed. 

• Secondary index is not auto-update. 

• The Indexed Access Method has a program error. 

Note: If you encounter another message while using $VERIFY, refer to 
the Messages and Codes manualin the EDX library for an explanation. 
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ERROR RECOVERY PROCEDURE 

If any of the $VERIFY file error messages are printed* use the folloming 
procedure* 

• Dump the file or portion of the file which $VERIFY indicated has 
errors. 

• Attempt to reorganize the file with the $IAMUT1 utility RO command. 

• If reorganization fails, submit an APAR, including the file dump. 

• Secondary indexes may need to be regenerated. Invoke $VERIFY for 
each of the secondaries to determine if they are error free. If 
errors are indicated rebuild the index from the primary data sets 
after the problem has been corrected. 



^VERIFY STORAGE REQUIREMENTS 

Working storage space is required for $VERIFY and the amount required 
varies, depending on the maximum number of blocks at the SIXB level and 
the block size of the file. 



USING DEFAULT WORKING STORAGE REQUIREMENTS 

The default working storage specification is 4K bytes. For a file with 
a block size of 256, this default is sufficient to handle up to 896 
blocks at the SIXB level. The larger the block size of the file, the 
fewer the maximum number of SIXBs that can be processed. 

The following formula can be used to calculate the maximum number of 
blocks at the SIXB level that $VERIFY can process, given the block size 
of the indexed file: 



/f 



NS = (^096 - (2 X BLKSIZE)) / 4 

NS is the number of blocks at the SIXB level 
BLKSIZE is the block size of the indexed file 



o 
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MODIFYING UORKING STORAGE REQUIREMENTS 

The default working storage allocation is intended to satisfy the 
requirements of most indexed files. It may be necessary or desirable to 
modify the amount of working storage space available to $VERIFY. 

The following formula can be used to calculate the amount of working 
storage required to process a file with a given block size and number of 
blocks at the SIXB level. 



D5 = (^ X NS) + (2 X BLKSIZE) 



WhereJ 

DS is the amount of dynamic storage required 

NS is the number of blocks at the SIXB level 

BLKSIZE is block size of the indexed file 

The number of SIXBs in a file can be determined by examining the free 
space report. 

You can override the default working storage size at load time (if 
loaded by a program), or with the SS command of the $DISKUT2 utility. 



SUMMARY 






$VERIFY requires a variable amount of working storage which defaults to 
4K bytes. Increase the working storage size if $VERIFY runs out of 
space during execution. 

Decrease the working storage size if the number of SIXBs is significant- 
ly less than that supported by the default working storage allocation 
(896 with a block size of 256) and your available storage is limited. 



#>1 
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CHAPTER 11. STORAGE AND PERFORHANCE CONSIDERATIONS 






This chapter describes the storage required for the Indexed Access Meth- 
od and offers suggestions for improving performance. The main topics 
ares 

• Determining Storage Requirements 

• Data Paging 

• Other Performance Considerations. 



DETERMINING STORAGE REQUIREMENTS 

The minimum amount of storage required by the Indexed Access Method is 
dependent upon the package you choose to install, plus the link module 
and any error exit routine you may have written. The approximate sizes 
of the available packages are included here for planning purposes. 



THE INDEXED ACCESS METHOD PACKAGES 






he Indexed Access Method program product is shipped Mith four packages: 

$IAM 

$IAMRS 

$IAMNP 

$IAMRSNP 

You select the particular package to install on your system which meets 
your requirements for function, storage, and performance. The individ- 
ual packages are described below^ 

1. $IAM — (23K). A full-function Indexed Access Method package using 
an overlay structure. It is expected to satisfy the needs of most 
users. 

2. $IAMRS — (32K). A full-function Indexed Access Method package that 
is fully resident. It requires more storage than $IAM, but offers 
maximum performance. 

3. $IAMNP — (20K). This package is similar to $IAM (using an overlay 
structure) but does not include data paging. It is designed for 
users who have severe storage limitations. 

4. $IAMRSNP — (29K). This package is similar to $IAMRS (fully 
resident) but does not include data paging. This package provides 
the performance of a resident system but is intended for users who 
do not have sufficient storage to take advantage of the data paging 
feature. 



Notes: 



The storage values above do not include Indexed Access Method con- 
trol blocks, the central buffer (minimum of 2 X block size), and 
secondary index update buffers (minimum of 2 X record size). 

To find the exact size of your Indexed Access Method package, load 
$IAM with the operator command $L. A message will be displayed 
about the loaded program. The number, followed by the letter P, 
indicates the size of the program in 256-byte pages. Multiplying 
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this number by 256 yields the size in bytes of §IAM» 
trol blocks^ work areas and buffers. 



including con- 



o 



INDEXED ACCESS METHOD STORAGE ENVIRONMENT 

A single copy of the Indexed Access Method load module $IAM serves the 
entire system. 



Figure 11-1 shows the components of the 
relationship to the operating system. 



Indexed Access Methods and their 



The Indexed Access Method control blocks^ buffers and programs are con- 
tained in a single module^ which can be loaded in any partition (but 
only one copy on the system) . 

Application programs in any partitions (including the partition contain- 
ing the Indexed Access Method) can invoke Indexed Access Method services 
using the IBM supplied link module^ which must be included in the appli- 
cation program. 

If the data paging feature of the Indexed Access Method is active^ it 
uses storage in the parti tion(s) you select for performance improvement. 
This storage is in the form of a load module^ $IAMSTGM. 
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Figure 11-1. Indexed Access Method Storage Environment 



Because $IAM is loaded automatically when the first Indexed Access Meth- 
od request is issued^ it does not need to be explicitly loaded before 
being used by any program. When loaded automatically on the first 
Indexed Access Method request* $IAM is loaded into partition 1 if enough 
storage is available there. If not, attempts are made to load $IAM into 
successively higher numbered partitions until space is found or no more 
partitions are available. Once loaded, the Indexed Access Method 
remains in storage until cancelled with the $C operator command. 

The Indexed Access Method can also be loaded manually by using the $L 
operator command or automatically at IPL time through a $INITIAL 
program. Refer to the Customization Guide manual in the EDX library for 
more information on using a $INITIAL program. 



^tiW^ 



11-2 3034-0771 



$IAM can be loaded into any partition. It can be loaded (through the 
link module) from application programs in any partition. 



o 



PERFORMANCE 



Performance can be improved by various factors and the performance will 
be different for each application. One performance consideration has 
been described previously, the resident Indexed Access Method packages 
$IAMRS and $IAMRSNP. Another supplied performance feature is data pag- 
i ng. 



DATA PAGING 



O 



Data paging is a performance feature that uses main storage space for a 
paging area (a cache) to improve the performance of the Indexed Access 
Method. This paging area retains recently used index and data blocks 
which have been retrieved for processing. As blocks are read from an 
indexed file, they are retained in the paging area on the assumption 
that they will probably be requested again. When a block is requested 
again, if it is in the paging area, no I/O operation is required; the 
block is moved directly into the central buffer. 

The paging area is divided into 2K-byte (2048-byte) pages. Each indexed 
file can also be thought of as being divided into 2K-byte pages. Uhen 
data is read from the file, a 2K-byte page is read and saved in the pag- 
ing area. When data is written to the file, only the modified block 
(not the 2K-byte page) is written. 

When the paging area becomes full, pages are overlaid according to a 
least-recently-used algorithm. The Indexed Access Method data paging 
algorithm handles direct access records differently from the way it han- 
dles sequential access records. 

SEQUENTIAL ACCESS AND DATA PAGING: All of the pages in the page area can 
be used for direct access. However, because sequential access can cause 
the page area to be flushed out (negating the advantages of data 
paging), only 25% of the pages are set aside for use in sequential mode. 
Therefore, pages referenced in sequential mode will only use a small 
portion of the page area. This causes the pages to tend to preempt 
themselves instead of flushing out the page area. 

REMOVAL OF STORAGE MODULES: The data paging area is obtained by loading 
a copy of $IAMSTGM into one or more partitions. Each copy of $IAMSTGM 
remains in storage, even if you cancel $IAM. Cancelling $IAM is not 
recommended unless you have ascertained that no files are currently open 
and no requests are about to be issued. If you have cancelled $IAM you 
can use the $C $IAMSTGM operator command to remove the data paging stor- 
age module from each partition. $IAMST6M should never be cancelled 
until you have first cancelled $IAM. 



Adjusting the Size of the Paging Area 




Figure 11-2 on page 11-5 shows the effect of various data paging area 
sizes on the percentage of times a requested block was in the paging 
area ("Hit Ratio") and the resultant performance (response time indica- 
tor) for one application. The data was acquired by measuring the pei — 
formance, and printing data paging statistics, while the application was 
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running. The total size of all indexed files being accessed during the 
run Mas 36592 sectors (9. 3M-byte5) . It must be stressed that this is 
only one application^ and your application may not behave in the same 
manner. 

The use of data paging does not affect the timing of the write. The 
timing of the write is always controlled by the immediate write-back 
function (described in paragraph [161 of "Setting Up An Indexed File 
Using $IAI1UT1" on page 2-2). 

The three variables considered in data paging described in this example 
are- 

• storage size dedicated to data paging 

• the percentage of times that the block requested is in the paging 
area ("Hit Ratio") 

• read/wr i te rat i o . 

STORAGE SIZE: The figure shows general trends for various storage sizes. 
Note that there is a minimum amount of storage which can provide a bene- 
fit. In this example the minimum storage to acquire a performance 
improvement is approximately 20k-bytes. This is because the data paging 
algorithms in the Indexed Access Method require a certain amount of 
processing^ which is additional overhead. Your application may have a 
different minimum. If you cannot supply enough storage to provide a ben- 
efit, you are better off not to use data paging. Uithin certain limits, 
the more storage you supply, the better the performance. However, there 
are optimal minimum and maximum limitations. Figure 11-2 on page 11-5 
shows that, for this example application, the minimum amount is about 
20k-byte5. 

The optimal maximum amount of storage, beyond which the benefit of using 
more storage becomes less pronounced, is about 70k-byte5 for the example 
shown in Figure 11-2 on page 11-5. You must determine, based on your 
own storage/performance trade-off requirements, how. much storage to ded- 
icate to data paging for the performance improvement you receive. Larg- 
er files require a proportionately larger paging area to attain the same 
hit ratio. 

THE "HIT RATIO": The values shown at the left side of Figure 11-2 on 
page 11-5 is called a "Hit Ratio". This ratio is a percentage of how 
often an index block or data block requested is already in the paging 
area. Most applications tend to concentrate activity in a few areas of 
the file for a time, then move on to other areas of the file. These 
applications can use data paging to good advantage because there is a 
probability that the data being requested has been recently requested. 

If your application references data in a completely random manner, data 
paging will be less efficient. Random applications result in a smaller 
hit ratio for a given paging area size than applications that concen- 
trate on certain areas of the file. Therefore, larger paging area is 
required to obtain the same hit percentage. 



THE READ/MRITE RATIO: The data paging function is optimized for read 
operations. In order to insure file integrity, write operations cause « 
write-through to the file. This means that there is no benefit in usin< 
data paging for write operations. In fact, due to paging overhead, 
write operations are less efficient with data paging than without data 



pagi ng. 

The higher your ratio of reads to writes, the more efficiently the data 
paging algorithm works, thus the better your performance improvement. 
In the example shown in Figure 11-2 on page 11-5, 80% of the requests 
were reads, 205J were writes. 
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This graph shous hoM the size of the data paging area (shown across the 
bottom) affects the hit ratio (shoMn on the left margin) » and the 
results in the response time (shown on the right margin). The unit of 
time for the response time scale is not given because it is application 
dependent. For this application^ a hit ratio of at least 28% (which can 
be achieved with a paging area size of about 20K) is required to attain 
performance equal to that without data paging active. This is due to 
data paging processing overhead. Also note that a paging area size of 
greater than about 70K provides relatively little response improvement 
for the amount of storage dedicated. 



Using Data Paging 

The Indexed Access Method is distributed with the paging area size set 
to zero; therefore, the data paging function is not enabled. To use 
paging, use the $IAMUT1 PP command to set the paging area size for each 
partition and the $IAMUT1 P6 command to activate paging. 

Uhen $IAN is loaded, the loader attempts to obtain storage in the 
requested partition. Uhen storage is requested in a particular parti- 
tion to activate paging, you are informed of the results with appropri- 
ate messages. The messages returned to inform you of the paging status 
are written to the $SYSLOG device. If $SYSL06 is not available, the 
messages are written to $SYSPRTR device. Following are the conditions 
which can result 5 

1. Data paging is successfully initialized. The storage you requested 
or the default amount of storage required for data paging is avail- 
able. The following message is displayed* 

"DATA PAGING ACTIVE." 

2. Data paging is not successfully initialized. 

a. If you have attempted to activate paging and you requested zero 
for the storage amount, or the minimum amount of storage neces- 
sary for paging is not available in the partition you specified, 
the following message is displayed: 

"NOT ENOUGH STORAGE AVAILABLE FOR DATA PAGING." 
"DATA PAGING NOT ACTIVE." 
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b. 



If you have requested more storage for paging than is available 
in the partition you specified* the following message is dis- 
played: 



LOAD FAILED FOR $IAMSTGM RC=xxx, PTN= Y, SIZE= zz 



o 



where: xxx represents the return code from the LOAD instruction 
y represents the partition number requested 
Z.Z. represents the size in 1024-bytes of storage 

you requested 



OTHER PERFORMANCE CONSIDERATIONS 



FolloMing is a list of subjects followed by some ideas you might use to 
affect the performance of your application: 

Looking at the File Structure 

Controlling the File size 

Reducing the Number of Index Levels 

Increasing the Buffer Size 

Sequential Processing 

Avoiding Resource Contention 

Using Block Mode. 



LOOKING AT THE 
is primarily d 
This structure 
the file. The 
the file struc 
it exists at a 
9, "The $IAMUT 
ue5» see Chapt 



FILE STRUCTURE: Performance of the Indexed Access Method 
etermined by the structure of the indexed file being used, 
is determined by parameters you specify when you create 
best performance from an indexed file is attained when 
ture is well planned and the free pool is rarely used, if 
11. For descriptions of the file parameters* see Chapter 
1 Utility." For examples of the effects of parameter val- 
er 3, "Defining Primary Index Files." 






Use the $IAMUT1 utility to see the effects of the various parameters on 
the file structure. 

FILE SIZE: A large file spans more cylinders of the direct access 
device* so the average seek to get the record you want is longer. 
Splitting files into smaller files according to application type* or 
moving seldom used records to a "history file" might be viable solutions 
for file size reductions. 

If your records contain unused or unnecessary fields* delete those 
fields and reduce your record length before defining and loading your 
file. The Sort/Merge Program Product contains facilities to accomplish 
this while sorting your records by key. 

REDUCING THE NUMBER OF INDEX LEVELS: A file with many index levels 

equires more accesses to get to the desired data record* thus degrading 
performance. Factors which influence the number of index levels are: 

Number of records in file — see "File Size" previously described. 

Amount and type of free space — see "File Structure" previously 
described. 

Block size — when defining your indexed file* remember larger block 
sizes usually require fewer I/O operations. 

Key size — shorter keys are more efficient than long keys. If only a 
portion of your key field provides uniqueness* set your key position 
and key length to that portion of the field when you define the 
file. 






11-6 SC3<^-0771 









INCREASING THE BUFFER SIZE: The buffers required for I/O operations for 
all Indexed Access Method requests throughout the system are taken from 
a single buffer pool. The size can be changed at any time (to become 
effective during the next load of $IAM) as described in "BF — Tailor the 
Indexed Access Method Buffers" on page 9-4. If you provide a large 
buffer when you install the Indexed Access Method, it is more likely 
that blocks (especially high-level index blocks) needed are already in 
storage and need not be recalled from the file. 

A possible exception to this consideration is found in the following 
section on sequential processing. 

SEQUENTIAL PROCESSING: In certain caseSf sequential processing perform- 
ance can be improved by reducing the size of the lAM Central Buffer (us- 
ing the BF command of $IAMUT1). In such a case, reduce the lAM Central 
Buffer size only for the duration of the sequential processing and then, 
only if sequential processing is the only activity. 

Uhether or not your application will experience a performance improve- 
ment will depend on the blocking factor (records per block) » the block 
size of the file being processed^ and the type of processor in use. 

lAM buffer management serves to provide optimal performance in most 
environments by bypassing disk l/0*s if a requested block is in storage. 
This process entails some overhead which may not be neccessary if a file 
is being processed sequentially since an I/O must always be issued to 
read or write the next block. The overhead is greatest if the file's 
block size is small, with a low blocking factor. 

You may find the best performance improvement by allocating enough lAM 

central buffer space for two blocks and two buffer table entries. A 

buffer table entry requires 14 bytes. The block size that you use in 

this calculation should be the largest block for the file(s) being proc- 
essed in sequential mode. 

This consideration applies when sequential processing is the only lAM 
activity taking place in the system, and only one task is accessing a 
given JAM file. This consideration does not apply in the case of GETB 
or GETNB operations. In these cases, system operation bypasses the lAM 
central buffer. 



AVOIDING RESOURCE CONTENTION: Application programs that use the Indexed 
Access Method are executed the same as other application programs. 
Because the Indexed Access Method and the indexed files are resources 
available to all tasks, delays can occur. Ulhen more than one task uses 
the Indexed Access Method, contention can occur between tasks for any of 
the following resources: 

• An entire indexed file 

• An index block in the file 

• A data block in the file 

• A data record in the file 

• Buffer space from the system buffer pool. 

For example, during the execution of a request from task A, some buffer 
space is required and an index block, data block, or record is locked 
(made unavailable to other requests). A request from task B requires 
more buffer space than is available or attempts to retrieve a block or 
record that was locked by task A. Task B must wait until the required 
resource becomes available. 

Resources required by the Indexed Access Method are allocated only for 
the duration of a request except under the following circumstances: 

• During an update, when control returns to the task after a GET or 
GETSEQ for update, the subject record is locked. The lock is 
released when the update is completed with a PUTUP, PUTDE, RELEASE, 
or DISCONN. 
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• During sequential processing^ Mhen control returns to the task after 
a GETSEQy the block containing the subject record is locked and held 
in the buffer. 

Subsequent GETSEQ requests pick up records directly from the buffer, 
klhen a GET requires a record from the next blocks the current block 
and buffer are released. Pending requests for a buffer area are 
satisfied and the next block is locked and held in the buffer. 
Except for momentary release of the buffer area between blocks, a 
block is locked uihile it is being processed. Processing is termi- 
nated by an end-of-data condition, an ENDSEQ request, a DISCONN 
request, or an error condition. 

Use the following guidelines to avoid resource contention: 

• Disconnect all indexed files before task termination. The DISCONN 
request releases locked records or blocks and writes records that 
have not already been written. 

• Use conditional requests whenever possible so that your application 
can be productive while a resource is unavailable. 

• Try to schedule applications so that they do not execute at the same 
time. 

• If a file is used for "read only" by more than one application, con- 
sider multiple copies of the file using unique file names. 

• Uith multiple Indexed Access Method applications, use direct access 
to retrieve a group of records. A suggested method is the 
following: 

1. Retrieve the first record by key. 

2. Extract the key from the record and save it for the next 
retri eval . 

3. Retrieve the next record using the saved key and a greater than 
key relational operator (GT or UPGT). 

4. Repeat the second and third steps until processing is complete. 



USING BLOCK NODE 



Applications that process primary files sequentially should improve per- 
formance by using the block I/O feature of $IAM. This feature enables 
$IAM to read data blocks directly into a buffer area you set up in your 
application program. Subsequent requests for data from that block are 
then handled within your program by the lAM link module and $IAri is not 
called again until the program requests a record not contained in that 
block. 

Record level block I/O is most effective in applications that do a lot 
of sequential processing. 

The main drawbacks of block I/O are: 

• The feature is supported only for applications written in EDL . 

• The block in the user buffer area is locked, so no other application 
may access it. The block remains locked until the program replaces 
it with another, issues an ENDSEQ in sequential mode, or issues a 
DISCONN. 

• Each application areas needs a buffer area the size of the file 
block size + 36 bytes. This storage is required for each file 
opened in block mode. 



c 
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Each application needs to have the block I/O stub module lAMFR and 
the module lAM linked in. This increases the size of the applica- 
tion by 4.3K. 

Block mode support is not available for applications using 
high-level languages. 

There are two ways to use the block I/O feature. 

— Record-level block I/O 

— High speed block reads. 



Record Level Block I/O 

Record Level Block I/O allows you to use all of the regular lAM requests 
such as GET and PUT, but $IAM puts the data block into the buffer area 
in your application program. If a request can be satisfied by the data 
in the buffer, then the lAM link module does all the processing and $IAM 
is not called. This cuts down on competition for $IAM. 

If the block mode file has auto-update secondaries, then PUTUP and PUTDE 
requests are invalid. The GET-foi — update/ PUTUP and PUTDE call sequence 
in this use should be replaced by a GET/ DELETE/ DELETE/ PUT sequence 
of calls. 

Requests that require a call to $IAM arei 

• DELETE - If the record is not in the block, if the record is the 

only record in the block, or if the file has 
auto-update secondaries. 

DISCONN - always 

ENDSEQ - always - to release the lock on the block. 

EXTRACT - always 

GET - If the record is not in the current block. 

GETSEQ - If the record is not in the current block. 

LOAD - not applicable 

PROCESS - always 

PUT - If the block is full, if the record does not go into this 
block, or if the file has auto-update secondaries. 

PUTDE - If the record is the only record in the block. 

PUTUP - never 

RELEASE - never 

Considerations for the use of record level block I/O are^ 

• The block in your programs buffer is locked, so no other application 
may access it. The block remains locked until the program replaces 
it with another, issues an ENDSEQ in sequential mode, or issues a 
DISCONN. 
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Each application needs a buffer area the size of the file's 
blocksize plus 36 bytes. This storage is required for each file 
opened in block mode. 

Each application needs to have the block I/O link module lAMFR 
linked in. This increases the size of the application by approxi- 
mately 3.5K. Refer to Appendix B, "Preparing Indexed Access Method 
Programs" on page B-1 for additional information. 

Files that ar& opened in block mode which have immediate write-back 
on have their block locks released and the block written back with 
each write operation (PUT, DELETE, PUTUP, and PUTDE), even if the 
request can be satisfied entirely within the current block. 

Files that have auto-update secondaries cause the stub to write the 
block back on every PUT and DELETE. This is to allow the secondary 
file to be updated. PUTUP and PUTDE are not allowed in block mode 
against files with auto-update secondaries. 



High Speed Block Reads 

In block mode, $IAM reads the data block into a buffer in the user pro- 
gram. It is therefore possible for the application program to process 
the records in the block itself, going to the link module only to 
retrieve records not contained in the block on hand in the buffer. Two 
requests, GETB and GETNB have been implemented to facilitate processing 
records in blocks. Both requests require the file to be opened by the 
PROCESS request in block mode. 

Like GET, GETB places the block containing the record that satisfies the 
key condition in the user block I/O buffer area specified in the PROCESS 
request. The difference is that the third parameter, instead of being a 
record area, is a pointer to the address of the word in the block. 

The GETNB request uses the forward pointer in the header of the current 
block in the program's buffer area to read the next block of data. 

By using GETB and GETNB, your program can read quickly through a file in 
a sequential manner. Note that there is no "sequential mode" concept 
with these requests and a GETB may be issued at any point in a series of 
GETNB requests to move backward or forward in the file. 

The GETB and GETNB requests are designed to be used by applications that 
need to read data, and not to write it. You must code an application 
using these requests to process blocks of data in its own buffer. To 
help you, lAMEQU contains equates that point into the buffer to the 
start of the data. You may may want to use the information in the buff- 
er heading to determine, for example, how many data records are in the 
block. 

Note that if a file is opened in block mode, the PUT and DELETE commands 
can still be issued against it. These commands cause the block in the 
buffer to be written to disk and therefore update the data file. Ensure 
that the data in the buffer is not altered incorrectly if it will be 
written back out. 



/f 



W 



11-10 SC3<>-0771 



o 



Each block that is read into the user buffer is locked. This locking 
requires a call to $IAM. To avoid this call» the application can open 
the file for exclusive use (EXCLUSB) in block mode. This prevents other 
programs from accessing the file until it is DISCONNECTED, uihile allow- 
ing the fastest possible processing of the data file. 



^f"*%, 



Secondary Index Functions 

Using secondary indexes affects the performance of the Indexed Access 
Method. Some of those reasons are described here. 

DIRECT RETRIEVAL: Direct retrievals are somewhat slower when using a 
secondary index because of the extra accesses required to retrieve the 
data record from the primary file. 

SEQUENTIAL RETRIEVAL: Sequential Retrievals are slower when using a sec- 
ondary index because the records are returned in order by secondary key. 
The primary file containing the data records is in order by the primary 
key. Therefore, the records are not stored in the same sequence that 
they are retrieved. This requires random accesses to obtain the 
records. 

RECORD INSERTS: Record inserts are slower if any associated secondary 
indexes have the auto-update indicator on. A new record must be 
inserted into each auto-update secondary index, as well as the primary, 
whether the original insert was a primary or a secondary. 

RECORD DELETE: Record deletes are slower for the same reason as for 
inserts; records must be deleted from secondary indexes that have the 
auto-update indicator on. However, the impact for deletion is more 
severe than for insertion. This is because a search is required when 
multiple records have the same value for their secondary key as the 
record being deleted. The group of records having the same key must be 
sequentially searched until the record with the required primary key is 
found. This time could be quite significant if you have large groups of 
duplicate keys. 

RECORD UPDATE: Record updates that modify the secondary key must also 
update any associated secondary index which has the auto-update indica- 
tor on. The secondary index is updated by deleting the old key and 
inserting the new key. 

DATA RECORD MOVEMENT: Each record in a secondary index contains a point- 
er to the RBN where the record is located in the primary index file. If 
a data record has been moved, due to insert/delete activity in nearby 
areas of the primary file, the RBN in the secondary index record will be 
wrong. Uhen the affected data record is retrieved through the secondary 
index, the error is detected. A full retrieval is then performed, using 
the primary key to obtain the data record. The RBN in the secondary 
index record is then updated for the benefit of future retrievals. This 
activity will affect the performance. 

^VERIFY PERFORMANCE: The $VERIFY performance will be slower when the 
primary file being verified has a secondary index with large numbers of 
duplicate secondary keys. This is because the entire group of duplicate 
keys must be searched for the proper record. Because $VERIFY retrieves 
all records in the file, these impacts accumulate and the total exe- 
cution time can be longer than expected. 
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CHAPTER 12. ERROR HANDLING AND RECOVERY 



This chapter describes hoM to handle Indexed Access Method errors and 
houi to diagnose application program errors. The major headings are? 

• "Return Codes" 

• "Error Exits" on page 12-2 

• "Aids for Analyzing Problems" on page 12-3 

• "Application Program Considerations" on page 12-9. 



RETURN CODES 



1^' 



All Indexed Access Method requests return a code in the task code Mord 
of the Task Control Block (TCB). The task code Mord is the same name as 
the task name. The return code reflects the condition of the requested 
function. Return codes are grouped i n the following categories^ 

-I Successful completion 

Positive Error 

Negative Warning (other than -1) 



SYSTEM FUNCTION RETURN CODES 

If a system function called by an Indexed Access Method request ends 
Mith a positive return code» the return code is placed into a location 
named by the SYSRTCD parameter in the PROCESS or LOAD request. This 
location is used until a DISCONN is issued. 

For example* the GET request uses the supervisor read function. If the 
read ends with a positive return code» that return code is saved in the 
location named by the SYSRTCD parameter in the PROCESS request associ- 
ated with the GET request. The GET request also ends with a positive 
return code in the task control word. The positive return code indi- 
cates that a read error has occurred. The cause of the read error can 
be determined by examining the location named by the SYSRTCD parameter. 

Note: Uhen analyzing errors* the Indexed Access Method return 
code in the task code word should be checked prior to the system 
return code. 
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The folloMing example is a method of obtaining the return code value 
from the location SYSRTCD. This routine gets the task SYSRTCD* and com- 
pares it to the EDX successful return code* negative one (~1). 



YOURPRGM 


PROGRAM 


START 






SUBROUT 

MOVE 

IF 


ERRTEST 

TASKRC, SYSRTCD 
(TASKRC, EQ,-1) 


get system return code 
if -1, return now 




; 




if not -1 then perform 




ENDIF 
RETURN 




your diagnosis 


TASKRC 


DATA 


F'O' 


saved system return code 



(p) 



ERROR EXITS 



There are three types of error exits for your application* 

• Task error exit, provided by the supervisor 

• Error exit, provided by the Indexed Access Method 

• The task error exit used by the Indexed Access Method itself in case 
of an error. 



TASK ERROR EXIT 



You can specify a task error exit routine that will receive control if 
your application program causes a soft exception or if a machine check 
occurs during the execution of your application. 

Because your application may have requests pending (for example, a 
record is being held for update or a file is being processed sequential- 
ly), you should issue a DISCONN request before terminating your applica- 
tion. The task error exit allows you to release records, disconnect 
from any file you are connected to, and make your resources available to 
other applications. Use of the task error exit facility helps to ensure 
data integrity and allows proper termination or continuation of your 
appl ication. 

Implementing the task error exit facility is described in the 
Customization Guide of the EDX library. 

Notes An error exit is taken if an error is encountered on a 
DISCONN call to the Indexed Access Method; this could result in a 
continuous loop. 



o 
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ERROR EXIT 



o 



In PROCESS and LOAD requests^ the address of an error exit routine can 
be specified by the ERREXIT parameter. If specified* this routine is 
executed whenever an Indexed Access Method request ends Mith a positive 
return code* except for return codes 1, 7, 8, and 22. 

If the exit routine is not specified* the next sequential instruction 
after the request is executed regardless of the value of the return 
code. 



$IAN TASK ERROR EXIT 



The Indexed Access Method itself has a task error exit. If this error 
exit is given control by the supervisor* it writes these messages to the 
$SYSLOG device: 



$IAM HAS INCURRED A SEVERE ERROR 

$IAM CENTRAL BUFFER ADDRESS IS xxxx - PARTITION n 

PSW LSB 

yyyy ^z.7i:z tltlz-z. -ztltlz. 'z:z.z.z. ^7L:Z.7i :!.Z.7iZ zzzz zzzz zzzz zzzz zzzz 






Ulhere xxxx is the address of the $IAM central buffer* and n is the par- 
tition containing $IAM. 

The PSW (yyyy)* and LSB contents (zzzz)* are also listed. For an expla- 
nation of the PSW (program status word) and the LSB (level status 
block)* refer to the Problem Determination guide of the EDX library. 

$IAM then goes into an unrecoverable wait and will not process any 
access requests. You can dump the central buffer with the $D system 
command and take appropriate action to complete your application (refer 
to the Operator Commands and Utilities Reference in the EDX library for 
a description of the $D command). 

You can use the recovery and backup procedures* described under "File 
Backup and Recovery" on page 7-9* to restore the file* or you can resume 
execution of your application. To restart your application* you can 
either IPL or cancel $IAM and reload it. 

If you wish to extend the logic of the error exit* code your own exit to 
replace the $IAM task error exit. Then rename CDIERR (the $IAM task 
error exit)* name your error exit CDIERR* and rebuild $IAM. 



AIDS FOR ANALYZING PROBLEHS 

You can get data to find out what is causing your problem by* 

• Determining the error return code. If system error logging is 
active* use the $ILOG utility to find out what errors have occurred. 

• Using a system dump. A system dump tells you how to locate the 
access method control blocks* wait states* and how to check for a 
loop. 

• Verifying and diagnosing your file. For information on using $VERI- 
FY* see Chapter 10* "The $VERIFY Utility" on page lO-l. 
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Note: If a wait condition occurs or the system terminates^ print the 
contents of processor storage using the $TRAP/$DUMP utility. See the 
Operator Commands and Utilities Reference for information on how to use 
these utilities. 



USING $ILOG - ERROR LOGGING FACILITY 



This section describes how to use the Indexed Access Me 
data set with your system. To use the error logging fa 
your system has an error log data set. The data set mu 
of three 256-byte EDX records. The first two records a 
trolf and this would allow one error log entry. The er 
are entered in the log data set one after the other as 
the data set becomes full* the new entries overlay the 
starting at the front of the data set again. Therefore 
data set should be based on the frequency of errors* an 
with which the data set is listed or examined. Each er 
requires a 256-byte EDX record. 



thod error log 
cility> be sure 
st be a minimum 
re used for con- 
ror log entries 
they occur, klhen 
old entries 

the size of the 
d the frequency 
ror log entry 



You can load $LOG into any partition. The system command $LOGINIT ini- 
tializes and activates error logging for any Indexed Access Method 
errors. 

To list the Indexed Access Method error log entries currently in the 
system error log, you can load $ILOG using the system command $L. 
Respond to the prompt "(DSNAME, VOLUME) :" with system error log data set 
and volume name. 



The list will be directed to the terminal which was used to load $ILOG. 

Following is a sample of the printed error report showing two error 
records: 



INDEXED ACCESS METHOD LOG 


REPORT 


PROGRAM 


ACTIVE 






TCB 
PTN ADDR 


DSNAME VOLUME 


ORIG 
FNCTN 


CURR 
FNCTN 


$IAM SYSTEM 
RTCODE RTCODE 


DATE 


TIME 


2 1F64 
2 1F64 


lAMFILE EDX002 
lAMFILE EDX002 


PUTNW 
PUTNW 


PUTNW 
PUTNW 


62 -1 
62 -1 


00/00/00 
00/00/00 


00:00:00 
00:00:00 


2 INDEXED ACCESS METHOD 


LOG ENTRIES LOCATED 






$ILOG ENDED 
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USING THE SYSTEM DUMP AND THE $EDXLINK MAP 

To use the system dump and the $EDXLINK map» first locate the access 
method control blocks by finding the load point of $IAM. To find the 
load point (starting address) of $IAMf check the program names in front 
of the dump. Next^ find the $IAM link map. The link map tells you 
Mhere the entry points are in storage. These entry points include con- 
trol blocks^ module names» Nork and overlay areas. 

If you have customized the access methods you have access to the link 
map. If you have not modified the access method, see the Link Controls 
section of the Program Directory. It contains an explanation of how to 
generate a link map corresponding to each of the access method packages 
($IAM, $IAMRS, $IAMNP, $IAMRSNP). 

After you have obtained the correct link map, find the pointer to 
CDIMCB. CDIMCB is the master control block. Once you find the entry 
point (address) for CDIMCB, add the loadpoint address of $IAM to the 
displacement of CDIMCB. This gives you the location of CDIMCB (MCB) in 
the system dump. 

The control blocks section of the program directory explains how to gen- 
erate a listing of the master control block (CDIMCBM, which contains all 
the fields and their addresses. 



Locating Information in the System Dump 

The following information on file control blocks (FCBs) and Indexed 
Access Method Control Blocks (lACBs) is useful when locating 
i nf ormat i on. 

FILE CONTROL BLOCK tFCB) CHARACTERISTICS: FCBs are located within $IAM 
in a pool of FCBs. The link map tells you where CDIIAM is. The address 
of the oldest FCB in use can be found in MCBFCBQH of CDIMCB. All cur- 
rently used FCBs are chained together by FCBQPTR (FCB queue pointer). 

To locate the FCBs within $IAM, find the entry point within CDIIAM 
called CDISTFCB and add this address to the load point address of $IAM. 
The word at the resulting location contains the starting address of the 
FCB pool. 

The Control Blocks section of the Program Directory explains how to gen- 
erate a listing of the file control block (CDIFCBM and CDIFCBXT) which 
contains all of the fields and their addresses. 



lACB CHARACTERISTICS: 
Access Method Control 



The link map also points to the lACBs (Indexed 
Blocks). These lACBs: 



• Connect your application to an access method file 

• Contain control information for the request 

• Are located within $IAM in a pool of lACBs. 

To locate the lACBs within $IAM, find the entry point within CDIIAM 
called CDISTICB and add this address to the load point address of $IAM. 
The word at the resulting location contains the starting address of the 
lACB pool. 

The Control Blocks section of the Program Directory explains how to gen- 
erate a listing of the file control block (CDIICBM) which contains all 
the fields and their addresses. 
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Analyzing Uait States 

There are several types of wait states. If the access method is 

uaiting> locate the access method master control block (MCB) to find out 

why. Find out the address of the MCB in the $IAM link map at label 
CDIMCB. You may ask: 

• Why is $IAM waiting? 

— There may be no request on the dispatch queue^ or 

— No requests on the dispatch queue are active. These requests 
may be^ 

— Waiting on locks 

— Waiting on buffers 

• Do you have requests on the dispatch queue? Find: 

MCBHEAD in CDIMCB. MCBHEAD points to the first lACB referenced 
on the dispatch queue. 

— MCBLASTL in CDIMCB. It points to the last lACB referenced on 
the dispatch queue. 

ICBNEXT in each lACB. It points to the next lACB on the dis- 
patch queue. 

— If MCBHEAD is zero, there are no requests on the dispatch queue. 
Check your application program to see if it regained control 
after the $IAM request. 

• Is each lACB in a wait state? 

Check each lACB. Note that ICBFLA63 is in the lACB. If the 
lACB is waiting, bit 6 (ready flag) and bit 7 (post flag) will 
be off. 

• Why is the lACB waiting? The lACB may be waiting for a^ 

— lock 

— buffer 

— If the lACB is waiting for a buffer, check the buffer queue. 
Find MCBBUFQH in CDIMCB, and find MCBBUFQE in CDIMCB. If both 
fields are zero, they are not waiting on a buffer. Try locking. 

— Where are the buffers? First check each lACB for^ 

— ICBFLAGl — Is the ICBPRIBF (primary buffer flag) on? 

— ICBFLAG4 — Is the ICB5ECBF (secondary buffer flag) on? 

— Is there any buffer space, and how much? 

— If MCBBUFNX equals MCBBUFEN, then there is no buffer space 
left. 

— If MCBBUFNX is not equal to MCBBUFEN, subtract MCBBUFNX from 
MCBBUFEN. This tells you how much buffer space is left. 

— If there are any lACBs that have buffers, the size of these 
buffers should make up the remaining buffer area. 
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Analyzing Abnormal System Termination 

If the system terminates^ do the following*. 

• Check the FCB chain which contains an FCB for every file opened to 
the access method. A single file can have multiple users» but has 
only one FCB. The MGB contains the address of the first FCB in the 
chai n. 

• Check the block lock queue and the record lock queue in each FCB. 
These queues contain pointers to the lACBs for requests that are 
waiting for specific records to unlock. Several requests can be 
outstanding and are held up due to either an earlier request for this 
same records, or a record within the same block has not yet been 
released. 

• Check the buffer queue in the MCB to ensure that the buffer pool is 
large enough. If all the space in the buffer pool is being used/ 
the lACBs on the buffer pool queue can not obtain buffer space. 



Analyzing Run Loops 

If your system is running in a continuous loop: 

1. Try to determine the area of the loop 

2. Take a system dump with your dump utility 

3. Use $VERIFY, to ensure that the data set is correct. 

• If the data set is incorrect^ 

— Rebuild the data set. Your data set could be incorrect if 
the system went down in the middle of an operation. 

— Run the application again. 

• You can also use one of the following to find the cause of your 
looping problem* 

"" $TRAP — To check for a class interrupt » you can use the 

$TRAP utility to save the contents of the hardware registers 
and processor storage. You can then use $DUMP to format 
this information. 

— Programmer's Console — If a programmer's console is avail- 
able, you can determine the address range of the loop with 
the Stop and Instruction Step buttons. 

~ ^DEBUG — Once you determine the storage addresses of the 
loop, you can use the $DEBUG utility to trace the storage 
area and determine the name of the program that is looping. 

~ ^LOG — To check for an I/O error, you can use the $LOG util- 
ity to record the I/O error log information. You can then 
use the $DISKUT2 utility LL command to list the contents of 
the log data set for analysis. 

Refer to the Operator Commands and Utilities Reference for specific 
information on using these utilities. 



o 
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Analyzing Data Paging Problems 

To find if paging is active, check the flag MCBDPAG in CDIMCB. If the 
flag is on, data paging is active. 

The page control block (PCB) contains several entries that are useful in 
problem determination. The location of the PCB in a dump of the system 
is determined as follows: 

• Determine the placement of the PCIPCB from your link map. 

• Then, add the loading point address of $IAM to the displacement of 
CDIPCB for its location in the dump. 

The Control Blocks section of the Program Directory explains how to 
generate a listing of the page control block (CDIPCBM and CDIPTEM) 
which contains all the fields and addresses. 

The following fields in the PCB are helpful in problem determination. 

Field Description 

PCBLRU Pointer to the least recently used page table entry. 

PCBMRU Pointer to the most recently used page table entry. 

PCBMRUSQ Pointer to the most recently used page table entry referenced 
in sequential mode. 

PCBHASHT Pointer to the hash table. 

PCBPTCUR Pointer to the first page table on the page table chain. 

PCBPAGID Page ID of the last page accessed in the page area. The page 
ID consists of- 

PCBFCBa FCB address of the file containing the page. 

PCBPAGEtt Page number of the accessed page. 

PCBBTE The buffer table entry of the last page accessed (where to 
copy to/from) . 



Determining Page Identification 

The page identification consists of three wordsJ 

FCB address — 1 word 

Page number — 2 words 
The page number is determined using the following calculation 

(Sectors per block ^ RBN)/5ectors per page 
The number of sectors per block is determined as follows^ 

Block size/ sector size 
The number of sectors per page is determined as follows^ 

2048/Sector size of the device 



o 
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Locating a Page 

To locate a page in the page area^ do the following: 

1. Take the page identification (FCB address and page number) and gen- 
erate a hash table entry number using the hashing algorithm. 

2. Go to the selected hash table entry and test the free bit. If the 
entry is free (all zeros) » the page is not in the paging area. 

3. If the hash table entry is not free, use the pointer to the page 
table entry to see if the page identification (in the page table 
entry) matches the requested page identification. 

4. If the page identification does not match, and the conflict list 
pointer is not null, use the conflict list pointer to locate the 
next entry to process in the page table. Check the page identifica- 
tion to see if this is the entry you want. Continue until you reach 
the end of the conflict list (the first word of the conflict list 
forward pointer contains X'FFFF') or you find the desired entry. 

5. If the end of the conflict list is found without a hit, you should 
assume the page is not in the paging area. 



APPLICATION PROGRAM CONSIDERATIONS 

This section describes a number of considerations to keep in mind when 
running application programs. 






VERIFYING REQUESTS AND FILES 



Following are two steps you can take to help you isolate and correct 
malfunctions in your Indexed Access Method application program. 

• Request verification — to determine that requests are correct check 
all parameters specified or defaulted on the Indexed Access Method 
CALL statements* 

~ PROCESS/LOAD requests — When issuing a PROCESS or LOAD, check 
that the specified file name is the correct file control block 
(DSCB) for the file you are verifying. 

— GET-PUT-PELETE-RELEASE requests — For these requests, carefully 
check the key, its position, length, and the relational operator 
(if used). Ensure that the correct address for the indexed 
access control block (lACB) is passed from the PROCESS or LOAD 
request, and that the record area address is correct. 

• File verification — read your $VERIFY report or indexed file dump to 
determine whether data or index records are missing or incorrect. 

Note: Be sure that the combination of parameters specified by the SE 
command of the $IAMUT1 utility to define your file is correct. See 
Chapter 9, "The $IAMUT1 Utility" for a description of the $IAMUT1 param- 
eters. 
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THE DATA-SET-SHUT-D0t4N CONDITION 

Sometimes an I/O error occurs that is not associated with a specific 
request. For example^ task A issues a GET on file X. To secure buffer 
space to satisfy the request, the Indexed Access Method attempts to 
write a block to file Y and, in writing the record, an error occurs. 
Data set Y is damaged but there is no requesting program to accept an 
error return code. 

The error is indicated by setting the data-set-shut-down condition for 
file Y. After this condition occurs, no requests except a DISCONN are 
accepted for file Y. 

Later, if task B issues a GET on file Y, the request ends with a 
data-set-shut-down return code. Task B should issue a DISCONN and use 
recovery and backup procedures as described under "File Backup and 
Recovery" on page 7-9, to reconstruct the file. To cancel the 
data-set-shut-down condition, initial program load (IPL) or cancel $IAM, 



DEADLOCKS AND THE L0N6-L0CK-TIHE CONDITION 

Because the Indexed Access Method uses record and block locks to pre- 
serve file integrity, deadlock and long-lock-time conditions may occur. 

The deadlock condition occurs when two or more tasks interact in such a 
way that one or more resources becomes permanently locked, making fui — 
ther progress impossible. A deadlock can also occur when two requests 
from the same task require a lock on the same record or a lock on the 
same block in sequential mode. 

A long-lock-time condition occurs when your program acquires a record 
for update and does not return the record to $IAM for a long time. 

Application tasks should avoid using the Indexed Access Method in such a 
way that a record or block remains locked for a long period of time, 
because other tasks may attempt to use the same record or block. In a 
terminal-oriented system, make every effort to ensure that a record or 
block is not locked during operator "think" time. Specifically, you 
should attempt to follow these rules^ 

• Do not retrieve a record for update, display the record at the tei — 
minal, and wait for the operator to modify it. 

• Do not retrieve a record in sequential mode, display the record at 
the terminal, and wait for an operator response. 

In both of these cases, a record or block is locked during operator 
"think" time and could be locked indefinitely. 

A deadlock cannot be broken except by freeing the locks (records) that 
are being waited on. 

If your application uses more than one lACB, deadlocks are possible. 
For example, one task has read record A and attempts to read record B, 
while another task has read record B and attempts to read record A. If 
you are using more than one lACB per task, such as in Multiple Terminal 
Manager applications, use ENQ/DEQ and interprogram communications to 
avoid the deadlocks. 



o 
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You can avoid the long-lock-time condition by using one of the following 
two methods J 

1. Retrieve the desired record without specifying update. Then^ 

a. Perform processing in a work area. 

b. Retrieve the record* specifying update. 

c. Compare the first record read in step 1 with the second record 
read in. If the records are identical, issue a PUTUP request* 
specifying the address of the copy in the work area. If they 
are not identical* issue a RELEASE request for the record read 
in step 3, and repeat steps 1 through 5. 

2. Use conditional requests which do not wait for locks. (See Chapter 
8, "Coding the Indexed Access Method Requests" for descriptions of 
coding conditional requests.) 

To retrieve records in sequential mode* use the technique described 
in "Avoiding Resource Contention" on page 11-7. 



o 
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CHAPTER 13. INSTALLING THE INDEXED ACCESS METHOD 



This chapter presents an overvieM of hoM to install the Indexed Access 
Method. 

The Indexed Access Method is distributed on two double surface 
diskettes. The diskettes are formatted at 256 bytes per sector. 



INSTALLATION PROCEDURES 



The installation information which follows is for planning purposes 
only. The specific details for installing the product are included in 
the "Program Directory", which is shipped with the product. 



INSTALLING THE INDEXED ACCESS METHOD 

Installing the Indexed Access Method consists of two steps: 

1. Step 1 

a. Ensure that adequate space is available for the installation 

according to the approximated requirements shown in Figure 13-1 






Volume 



EDX002 
ASMLIB 
ASMLIB 



Data Sets EDX Records 



Contents 



650 
75 



Load Modules 
Source Modules 
Link Module 



Figure 13-1. Volume Space Requirements 



2. Step 2 



b. 



Copy the Indexed Access Method load module ($IAM), the utility 
program ($IAMUT1), the load module ($IAMUT3)» the file verifica- 
tion program ($VERIFY), the log report program ($ILOG), and the 
source module which indicates level of Indexed Access Method 
installed ($5719IAM), to the EDX002 volume. 

Copy $IAMSTGM to the EDX002 volume if you will use the Indexed 
Access Method Data Paging support. 

Copy the following source modules and link module to the ASMLIB 
volume: lAMEQU, FCBEQU, lAM, lAMFR, and IDEFEQU. 



o 
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ASSEMBLING AND EXECUTING THE INSTALLATION VERIFICATION PROGRAM 

To assemble and execute the installation verification program^ 

1. Submit to the $JOBUTIL utility, the 'proc' $SAMPROC provided on vol- 
ume AM4001 to assemble and link edit the verification program. 

The source statements for the installation verification program Bre 
contained in a data set named SAMPLE on volume AM'+OOl. 

2. Use $IAMUT1 to define and allocate an indexed file to be used by the 
installation verification program. Respond to the SE option 2 
prompts with the indicated values^ 



BASEREC 


10 


FREEBLK 


10 


BLKSI2E 


256 


RSVBLK 





RECSIZE 


80 


RSVIX 





KEYSIZE 


28 


FPOOL 





KEYPOS 


1 


DELTHR 





FREEREC 


1 


DYN 


10 



3. Load $SAMPLE and when prompted for the data set and volume, respond 
with the name for the file allocated in the previous step 
(SAMPFILE). 

Note: The procedure $SAMPROC assumes that ASMWORK and LINKWORK 
data sets exist on EDX002. Allocate these data sets if they do 
not already exist with the $DISKUT1 Event Driven Executive 
Utility. Refer to the Operator Commands and Utilities Reference 
manual in the EDX library for details on allocation of these data 
sets. 



_>" 
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APPENDIX A. SUMMARY OF CALCULATIONS 



JTX 



The following calculations can be used to define an indexed data set. 
For a more detailed description of these calculati ons» see Chapter 
3, "Defining Primary Index Files" on page 3-1. In the calculations 
requiring division* results with non-zero remainders are either trun- 
cated or rounded up. To truncate is to drop the remainder; to round UP 
is to add one (only if the remainder is non-zero), and truncate. 



Data block 

^7^ Records per data block = block size minus 16, divided by 
record size; result truncated 

^tS Free records per block 

^^ Allocated records per data block = Records per block 
minus free records per block 

Index block (general) 

(4) Index entry size = key length plus 4; must be even-add 
rtfodd 

^n Total entries per index block = block size minus 16, 
divided by index entry size; result truncated 

Index block (PIXB) 

(6^ Free entries per primary index block (PIXB) = specified 
percentage of total entries per index block; result rounded up 

^7^ Reserve entries per PIXB = ^ecified percentage of total 
entries per index block; result rounded up. If free entries per 
FIXB and reserve entries per PIXB require all PIXB entries, 
subtract one from reserve entries per PIXB 

^g) Allocated entries per PIXB = total entries per index block 
mmus free entries per PIXB, minus reserve entries per PIXB 

Index block (SIXB) 

^\ Reserve entries per secondary index block (SIXB) = 
specified percentage of total entries per index block; result 
rounded up. If reserve entries per SIXB require all SIXB 
entries, subtract 1. 

(10) Allocated entries per SIXB = total entries per index 
block minus reserve entries per SIXB 



= (BLKSIZE -16)/RECSIZE 
=FREEREC 

0=0-0 



= KEYSIZE +4 (+1 if odd) 
= (BLKSIZE -16)/ 00 

= FREEBLK % of 

=RSVBLK%of 

(-1 if + = ) 

= 0-0-0 



=RSVIX%of 
(-lif0= 0) 



10) 



= © -0 
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Ddete OweOiotd 

(^ The number of blocks to retain in cluster (delete threshold) 
is calculated in one of three ways: 

a. If the RSVBLX parameter was not q>ecified: Number of 
blocks to retain in cluster * total entries per index block 

b. If the RSVBLK parameter was specified, but the DELIHR 
parameter was not q>ecified: Number of blocks to retain 
in cluster * allocated entries per PIXB, plus one-half of 
free entries per PIXB; result rounded up 

c. If the RSVBLK parameter was q>ecified and the DELTHR 
parameter was specified: Number of blocks to retain in 
cluster * q>ecifled percentage of total entries per index 
block; result rounded up. If the result is zero, set it to 1. 

Data in data set 

U2) Initial allocated data blocks = base records divided by 
aflocated records per data block; result rounded up 

^3^ Number of clusters in data set = initial allocated data 
Mocks, divided by allocated entries per PIXB; result rounded 
up 

(14) Total number of free blocks in data set - number of 
outters in data set, times free entries per PIXB 

Indexes in data set 

(i^ Number of primary index blocks (PIXBs) = number of 
cliuters in data set 

(1^ Number of secondary index blocks (SIXBs) = number 
of PIXBs, divided by allocated entries per SIXB; result 
rounded up 

Qj) Calculate the number of index blocks for levels 3 to n. 
Note that levels 1 (PIXB) and 2 (SIXB) have already been 
calculated. When the number of index blocks at a level is 1, 
n has been reached and the calculation is flniAed. 

Number of index blocks at level i (i = 3 to n) - number of 
index blocks at next lower level, divided by total entires per 
index block; result rounded up 

(is) Total number of index blocks = sum of index blocks at 
each level until a level containing a single index block is 
attained 



or 
® - © * © /2 ® 



or 



© =DELTHR%of © ® 
(If 0, set (n) tol) 



@ =BASEREC/ © ® 

© = © / © © 

® = @ • © 

© = 

® = © / © © 



© i- @ i-1/©® 

© ->!©' 

i= l-»-n 

where © 1= © 

© 2= © 

© n=l 
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Fteepool 

(^ Number of new data blocks which can be assigned to existing 
clwters *■ reserve entries per PIXB, times number of PIXBs 

(^ Number of new dusters (PIXBs) which can be created - reserve 
entries per SIXB, times number of SIXBs 

(sp Number of new data blocks which can be assigned to new 
dusters « total entries per index blocks, times number of new clusters 
which can be created. 

Q^ Maximum possible free pool = number of new data blocks \i^ich 
can be assigned to existing clusters, plus number of new clusters 
(PIXBs) which can be created, plus number of new data blocks 
^xMch can be assigned to new clusters. 

(^ Actual number of free pool blocks = specified percentage of 
maximum possible free pool; result rounded up. 

Size of data set 

G\ Total number of blocks in data set = 1 (for file control 
Mock), plus total number of index blocks, plus initial allocated 
data blocks, plus total number of free blocks in data set, plus 
actual nubmer of free pool blocks. 
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APPENDIX B. PREPARING INDEXED ACCESS METHOD PROGRAMS 



To prepare an application program that issues Indexed Access Method 
requests* perforin the following steps^ 

1. Enter your source program statements, using one of the Event Driven 
Executive text editors ($FSEDIT, $EDIT1, or $EDIT1N). 

2. Create the $EDXLINK control statements required to combine your pro- 
gram with lAM (and lAMFR if you are using Block I/O) and any other 
object modules you may need in your application (lAM and lAMFR are 
the link modules on ASMLIB). Use one of the text editors to perform 
this operation. 

3. Assemble or compile your source program. 

4. Use the linkage editor, $EDXLINK, to combine the object modules into 
a single load module, using the control statements prepared in Step 
2. 

Uhen the preceding steps are completed, the program is ready to be exe- 
cuted. 



Appendix B. Preparing Indexed Access Method Programs B-1 



A SAMPLE $JOBUTIL PROCEDURE AND LINK-EDIT CONTROL DATA SET 

The folloMing am examples of a $JOBUTIL procedure and a link-edit con- 
trol file used to prepare a program. 



o 



Sample $J0BUTIL Procedure 

The following $JOBUTIL procedure is an example of preparing an EDL pro- 
gram. 



X 

X THESE STATEMENTS WILL COMPILE, LINK, AND UPDATE THE 
X APPLICATION. 

X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

JOB COMPILE 

XXX COMPILE USERPROG SOURCE xxx 

LOG $SYSPRTR 

PROGRAM $EDXASM,ASMLIB 



OS 


USERPROG, EDX002 


SOURCE MODULE 


OS 


ASMWORK,EDX002 


ASSEMBLER WORK DATA S 


OS 


USEROBJ,EDX002 


ASSEMBLER OUTPUT 


PARM 


LIST $SYSPRTR 




EXEC 






JUMP 


END,GT,4 




JOB 


LINK 




LOG 


$SYSPRTR 




PROGRAM 


$EDXLINK,EDX002 




DS 


LINKWORK,EDX002 


WORK DSNAME 


X 




LINK-CONTROL DATA SET 


PARM 


LINKCNTL,EDX002 $SYSPRTR 


EXEC 






LABEL 


END 




EOJ 










o 
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Link Edit Control Data Set Example 



The following link-edit control records can be used to link-edit an 
Indexed Access Method application uiith the Indexed Access Method. 



X 

X LINK EDIT CONTROL DATA SET (LINKCTL) 
H 

INCLUDE USEROBJ,EDX002 INCLUDE APPLICATION PGM OBJECT 

INCLUDE IAM,ASMLIB INCLUDE INDEXED ACCESS METHOD 

INCLUDE IAMFR,ASMLIB INCLUDE BLOCK I/O SUPPORT 

LINK USERPROG,EDX002 REPLACE END 
END 



c 
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APPENDIX C. CODING EXAMPLES 



O 



This chapter demonstrates how to code the Indexed Access Method request 
functions by means of sample programs. This example uses Event Driven 
Language CALL functions. The second example uses the COBOL language. 
The third example in this chapter is coded using PL/I language. 



EDL INDEXED ACCESS METHOD CODING EXAMPLE 



This program gives a 
od function calls, 
ten base records are 
file is opened for p 
record whose key is 
retrieved sequential 
sequential mode. A 
updated. Another re 
record is inserted a 
Then/ an example of 
is shown. Finally* 
filers records is sh 
cessful completion t 
the console. 



n example fo 
The i ndexed 

loaded foil 
rocessi ng. 
greater than 
ly and then 
record is th 
cord is retr 
nd another o 
extracting i 
an example o 
own using th 
he message " 



r each of the major In 
file is opened first i 
owed by a DISCONNECT. 
A GET request i s perf o 
'JONES PW . Two more 
the ENDSEQ call releas 
en retrieved directly 
i eved sequentially and 
ne is deleted by their 
nformation from the fi 
f sequentially retreiv 
e fast block read supp 
Verification Complete" 



dexed Access Meth- 
n load mode and 

Next* the same 
rmed for the first 

records are 
es the file from 
by key and 

deleted. A new 

unique keys, 
le control block 
ing all of the 
ort. Upon suc- 

is displayed on 



o 



Although using secondary keys is not demonstrated in this example the 
requests are coded the same for secondary keys as they are for primary 
keys. When accessing secondary keys use the secondary index file name 
instead of the primary index file name. The Indexed Access Method will 
open the primary index file and retrieve the data record according to 
the secondary key requested if the secondary file has not been opened 
i ndependently . 

This program requires that an Indexed Access Method file has been 
defined with the $IAMUT1 utility with the following specifications' 



o 



BASEREC 


10 


BLKSIZE 


256 


RECSIZE 


80 


KEY5IZE 


28 


KEYPOS 


1 


FREEREC 


1 


FREEBLK 


10 


RSVBLK 





RSVIX 





FPOOL 





DELTHR 





DYN 






Appendix C. Coding Examples C-1 



o 



Q 



U 

a 

£ 
< 
X 

u 
o 



o 
o 
o 

o 

X 
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Ui 
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III 



9K 




X. 




)K ;k 


X 


X 


X X 








X 


X X 




X X 


)iC 




)K 




X 


X 


X 


X 






X X 


X 


X 
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X 


>K 
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X 
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X 






X X 
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X 
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X 
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X 






X X 


X 


X 


X 


X 


)K 




)K 
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X PERFORM SEQUENTIAL RETRIEVALS OF THE FIRST TWO RECORDS WHOSE x 
X KEYS ARE GREATER THAN OR EQUAL TO » JONES PW', AND THEN GET OUT x 
X OF SEQUENTIAL MODE. X 

X)()(XK)()()(XXMK)(X)(X)()()(XK)(XK)(X)(X)()(}(XK)()(KXX)()(X)(XM)(XX)(XX)(XXXX)(X)(X)()(XMXX)()(X)(XX)( 

CALL IAM,+GETSEQ,IACB,(BUFF),(KEY1),+GE 

CALL IAM,+GETSEQ,IACB,(BUFF) 

CALL IAM,+ENDSEQ,IACB,(BUFF) END SEQUENTIAL MODE 

SPACE 2 
XK)(X)()(X)()(XX)(XKX)(XXK)(XXXXXKXXXX)(X)()(KKM)(XXXXXXXMXXX)(X)()()()()(X)()(H)(XXXX 
X RETRIEVE THE RECORD WHOSE KEY IS 'JONES PW' FOR UPDATE. WHEN I 
X IS IN THE BUFFER, MAKE A CHANGE AND WRITE IT BACK. 

CALL IAM,+GET,IACB,(BUFF),(KEY1),+UPEQU 

MOVE BUFF+30,0 

CALL IAM,+PUTUP,IACB,(BUFF) 

SPACE 2 

X DELETE THE RECORD WHOSE KEY IS 'JONES PW' BY A SEQUENTIAL UPDAT 
X AND THEN GET OUT XQF SEQUENTIAL MODE, 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+GETSEQ,IACB,(BUFF),(KEY1),+UPEQU 

CALL IAM,+PUTDE,IACB,(BUFF) 

CALL IAM,+ENDSEQ,IACB, END SEQUENTIAL MODE 

SPACE 2 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
X INSERT A NEW RECORD WITH A KEY OF 'MATHIS GR' 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+PUT,IACB,(NEWREC) 

SPACE 2 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
X DELETE THE RECORD WHOSE KEY EQUALS 'LANG LK' 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+DELETE,IACB,(KEY2) 

SPACE 2 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

XEXTRACT THE FILE CONTROL BLOCK INTO THE EXTRACT BUFFER 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+EXTRACT,IACB,(EXTBUF),128 

MOVEA #1,EXTBUF #1 <— ACEXTRACT BUFFER) 

MOVE FLAGBYTE,(0,#1),BYTE OBTAIN FCB FLAG BYTE 

SPACE 2 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
X CLOSE THE FILE 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+DISCONN,IACB 

SPACE 2 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
X OPEN THE INDEXED FILE FOR PROCESSING IN BLOCK MODE 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

CALL IAM,+PR0CESS,IACB,(DS1),(0PENTAB),+SHAREB 

SPACE 5 



xxxxxxx 
T X 

X 

xxxxxxx 



xxxxxxx 
E, X 

X 

xxxxxxx 



xxxxxxx 

X 

xxxxxxx 



xxxxxxx 

X 

xxxxxxx 



xxxxxxx 

X 

xxxxxxx 



xxxxxxx 

X 

xxxxxxx 



xxxxxxx 

X 

xxxxxxx 
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NUMBER OF BYTES 
ADDRESS OF LAST RECORD 
MORE RECORDS IN BLOCK 



K LOOP THROUGH THE FILE USING GETB/GETNB COMMANDS X 

CALL IAM,+PROCESS,IACB,(DS1),(OPENTAB),+SHAREB 
CALL IAM,+GETB,IACB,(RECP),(KEYLOWV),(GE) GET 1ST BLOCK 
DO WHILE, (RTCODE,NE,+EOD) WHILE MORE RECORDS IN FILE 
MOVE #2,RECP DISPLACEMENT TO 1ST RECORD 

MOVE »1,BL0CKBUF,FRXUSECT NUMBER OF RECORDS IN BLOCK 
MULTIPLY »1,+RECLEN 
ADD #1,#2 
DO WHILE,(#2,LT,tl) 

MOVE BUFF, (0,t2)(+RECLEN, BYTES) RECORD INTO BUFFER 
)()<)(XXX)(MXXXXKXKXXX)(K)(X)(XKXX)(XKXXM)()(KKKXKX)()(X)(KXXXKXMX)()(KX)()(XX)()(XXXXX)(HK)( 
X AT THIS POINT YOU HAVE GOT A RECORD IN A BUFFER (BUFF) WHICH COULD K 
X BE PRINTED OR MANIPULATED IN SOME OTHER WAY. THIS EXAMPLE WILL X 
X MERELY BUMP THE RECORD POINTER AND CONTINUE THROUGH THE FILE X 
X SIMPLY READING ALL OF THE RECORDS UNTU NONE ARE LEFT X 

ADD «2,+RECLEN POINT TO THE "NEXT" RECORD 

ENDO 

CALL IAM,+GETNB,IACB READ IN THE "NEXT" BLOCK 

MOVE RTCODE, SAMPLE GET lAM RETURN CODE 
ENDO 
SPACE 5 

X WRITE VERIFICATION COMPLETE MESSAGE TO THE OPERATOR ^ 

ENQT 

PRINTEXT SKIP=1 

PRINTEXT VERIF,SPACES=0 
DEQT 

GOTO FINISH GO OVER ERROR EXIT ROUTINE 

SYSERR EQU x GETS CONTROL ON SYS/PGM CHK 

X WHEN A TASK ERROR EXIT IS SPECIFIED IN AN INDEXED ACCESS X 

X METHOD PROGRAM, THE USER MAY RELEASE ALL ACTIVE RECORDS AND X 

X BLOCK LEVEL LOCKS AS WELL AS DISCONNECT THE FILE ITSELF BY X 

X ISSUING THE 'DISCONN' CALL FOR EACH FILE THAT IS OPEN X 

X WRITE VERIFICATION COMPLETE MESSAGE TO THE OPERATOR X 

XXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

GOTO FINISH 

EJECT 

EQU X GETS CONTROL ON lAM ERRORS 

MOVE RTCODE, SAMPLE 

ENQT 



lAMERR 
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o 







PRINTEXT SKIP=2 








PRINTEXT RTCODMSG 








PRINTNUM RTCODE, TYPE= 


:S,FORMAT=(3,0,I) 






PRINTEXT SKIP=1 








PRINTEXT ERRMSG,SPACES=0 I 




DEQT 






FINISH 


EQU 


X 






CALL 


IAM,+DISCONN,IACB 






PROGSTOP 






EJECT 






)()(XXXX)()(X)(X)()(X)(XK)()(XM)(XXXXXXXX)()(XXX)(XXKXX)(KXXXXXXXXXXXXX)(XXXXXXK)(XX)(XX)(X | 


X DATA DEFINITION AND STORAGE AREAS 


K 


)(XX)(X)(KKX)(XK)()()(XM)(KXMK)()()(KH^)(X)(XX)()()(KXXX)()(XX)()()(X)(X)(XKXX)(XXMX)<KX)(X)(X)(XKX)( \ 


EOD 


EQU 


-80 


END OF DATA INDICATOR 


RCLEN 


EQU 


80 


SAMPLE RECORD LENGTH 


RECNUM 


DATA 


F*10' 


« OF RECORDS TO LOAD 


RTCODE 


DATA 


F'O' 


lAM RETURN CODE 


OPENTAB 


DATA 


F»0' 


SYSTEM RETURN CODE ADDRESS 




DATA 


A(IAMERR) 


USER EXIT ROUTINE ADDRESS 




DATA 


F»0» 


END OF DATA ROUTINE ADDRESS 




DATA 


A(BLOCKBUF) 


ADDRESS OF BLOCK I/O BUFFER 


RECP 


DATA 


F'O' 


POINTER TO 1ST RECORD 


BLOCKBUF 
RECORDl 


BUFFER 292, BYTES 


BLOCKSIZE+36 BYTES 


DATA 


CLSO'BAKER RG' 




REC0RD2 


DATA 


CL80'DAVIS EN» 




RECORDS 


DATA 


CLSO'HARRIS SL» 




RECORDS 


DATA 


CLSO'JONES PW 




RECORDS 


DATA 


CL80'JONES TR* 




REC0RD6 


DATA 


CL80»LANG LK' 




RECORD? 


DATA 


CLSO'PORTER JS' 




RECORDS 


DATA 


CLSO'SMITH AR' 




REC0RD9 


DATA 


CLSO'SMITH GA» 




RECORDIO 


DATA 


CLSO'THOMAS SN» 




FLAGBYTE 


DATA 


H'O' 


FCB FLAGBYTE 




DATA 


H'O' 
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NEUREC 
BUFF 

KEYLOWV 

KEYl 

KEY2 



KEY3 

lACB 

EXTBUF 

LOGON 

VERIF 

ERRMSG 

RTCODMSG 

X THE FO 

XKXXXX)(K 

TEECB 



HSA 
HSALSB 



CL«0'MATHIS GR» 
LENGTH=80 

2F»0' 

'JONES PW',LENGTH=28 

•LANG LK',LENGTH=28 

X'lC 



X'OO' 
»JONES PW 
F'0» 
64F'0» 



PREFIX FOR LOW KEY VALUE 
LOW KEY VALUE 



TOTAL LENGTH OF KEY 
USE ALL OF KEY 



DATA 
TEXT 
DATA 
DATA 
TEXT 
TEXT 
DATA 
DATA 
DATA 
DATA 
DATA 
TEXT 
TEXT 
TEXT 
TEXT 
EJECT 

XX)<KXXXKXK?<XXKXX)«XX)(XX?(KXXXXXXXXKXX)(X)(XKXXXXXXXXKKXXXJ(XXXXXJ(XX)?X 

LLOWING STORAGE IS USED BY TASK ERROR EXIT HANDLING ^ 

EQU X TASK ERROR EXIT CONTROL BLOCK 

DATA F»2» « OF DATA WORDS THAT FOLLOW 

DATA A(SYSERR) ADDRESS OF EXIT ROUTINE 
DATA A(HSA) ADDRESS OF HARDWARE STATUS AREA 
HARDWARE STATUS AREA. THIS STORAGE WILL BE FILLED IN 
BY HARDWARE UPON SYSTEM OR OR PROGRAM CHECK INTERRUPT 



ADDRESS OF lACB PUT HERE 
FCB PUT HERE BY EXTRACT 

•INSTALLATION VERIFICATION PROGRAM ACTIVE' 

'VERIFICATION COMPLETE' 

'VERIFICATION INCOMPLETE DUE TO BAD RETURN CODES' 

'INDEXED ACCESS METHOD RETURN CODE: ' 



EQU 

DATA 

EQU 

DATA 

DATA 

DATA 

DATA 

EJECT 

COPY 

EJECT 

COPY 

ENDPROG 

END 



X 
F'O' 

X 

F'O' 
F'O' 
F'O' 
8F'0» 

lAMEQU 

FBCEQU 



PROCESSOR STATUS WORD 

LEVEL STATUS BLOCK: 

ADDRESS KEY REGISTER 
INSTRUCTION ADDRESS REGISTER 
LEVEL STATUS REGISTER 
GENERAL REGISTERS 0-7 



o 
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COBOL INDEXED ACCESS METHOD CODING EXAMPLE 

This coding example inserts^ deletes, and updates records in an indexed 
file, using primary and secondary keys to retrieve the records. The 
indexed file is described beloM under "Input File". 



Program Description 

This program reads a record and based on a transaction code, either 
updates, deletes, or inserts records to a current Indexed Access Method 
file. The transaction type also determines whether indexing is done 
using a secondary or primary key. 



Input File 



o 



I. TRANSACTION FILE. 








TRANSACTION RECORD 


FORMAT: 




EMPLOYEE NUMBER 




1-6 


C6) 


LAST NAME 




7-21 


(15) 


FIRST NAME 




22-31 


(10) 


ADDRESS 




32-56 


(25) 


CITY 




57-68 


(12) 


STATE 




69-70 


(2) 


AGE 




71-72 


(2) 


START DATE 




73-78 


(6) 


TYPE 




79 


(1) 


ACTION 




80 


(1) 


II. UPDATE FILE 








A. MASTER FILE. 








PRIMARY. KEY IS 


EMPLOYEE NUMBER I 


B. NAME FILE 








SECONDARY. KEY IS 


LAST NAME 




EMPLOYEE RECORD 


FORMAT 




EMPLOYEE NUMBER 




1-6 


(6) 


LAST NAME 




7-21 


(15) 


FIRST NAME 




22-31 


(10) 


ADDRESS 




32-56 


(25) 


CITY 




57-68 


(12) 


STATE 




69-70 


(2) 


AGE 




71-72 


(2) 


START DATE 




73-78 


(6) 


FILLER 




79-80 


(2) 
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COBOLl. 



IBM-SI. 
IBM-SI. 



IDENTIFICATION DIVISION. 

PROGRAM-ID. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION, 

SOURCE-COMPUTER. 

OBJECT-COMPUTER. 

SPECIAL-NAMES. 

SYSOUT IS PRINTER. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT EMPLOYEE-MASTER ASSIGN TO DS2 "EMPMAST" "EDXTST" 
ORGANIZATION IS INDEXED 
ACCESS MODE IS RANDOM 
RECORD KEY IS EMPLOYEE-NUMBER 
FILE STATUS IS SK. 
SELECT EMP-NAME-FILE ASSIGN TO DS3 "EMPNAME" "EDXTST" 
ORGANIZATION IS INDEXED 
ACCESS MODE IS RANDOM 
RECORD KEY IS E-LAST-NAME 
FILE STATUS IS SK. 
SELECT TRANSACTION-FILE ASSIGN TO DS'i "TRANSF" "EDXTST" 
ORGANIZATION IS SEQUENTIAL 
ACCESS MODE IS SEQUENTIAL 
FILE STATUS IS SK. 
DATA DIVISION. 
FILE SECTION. 
FD EMPLOYEE-MASTER 

LABEL RECORDS ARE STANDARD 
BLOCK CONTAINS 3 RECORDS. 
01 MASTER-RECORD. 

05 EMPLOYEE-NUMBER PICTURE XC06). 
05 FILLER PICTURE X(74). 



FD 



01 



FD 



01 



EMP-NAME-FILE 

LABEL RECORDS ARE STANDARD 

BLOCK CONTAINS 3 RECORDS. 

EMP-NAME-RECORD. 

05 FILLER 

05 E-LAST-NAME 

05 FILLER 



PICTURE X(06). 
PICTURE X(15). 
PICTURE X(59). 



TRANSACTION-FILE 

LABEL RECORDS ARE STANDARD 

BLOCK CONTAINS 3 RECORDS 

RECORD CONTAINS 80 CHARACTERS. 

TRANS-ACTION-RECORD PICTURE X(80). 
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o 



UIORKING 


-STORAGE SECTION. 




77 


EOF 




PICTURE 9(01) VALUE ZERO. 


77 


ERR 


-SWITCH 


PICTURE X(01) VALUE ZERO. 


77 


SK 




PICTURE X(02) VALUE ZERO. 


01 


EMPLOYEE-RECORD. 






05 


MAN-NUMBER 


PICTURE X(06). 




05 


NAME. 








10 LAST-NAME 


PICTURE X(15). 






10 FIRST-NAME 


PICTURE X(10). 




05 


STREET-ADDRESS 


PICTURE X(25). 




05 


CITY 


PICTURE X(12). 




05 


STATE 


PICTURE X(02). 




05 


AGE 


PICTURE X(02). 




05 


START-DATE 


PICTURE X(06). 




05 


FILLER 


PICTURE X(02). 


01 


TRANSACTION-RECORD. 






05 


T-NUMBER PICTURE X(06)- I 




05 


T-NAME. 








10 T-LAST-NAME 


PICTURE X(15). 






10 T-FIRST-NAME 


PICTURE X(10). 




05 


T-STREET-ADDRESS 


PICTURE X(25). 




05 


T-CITY 


PICTURE X(12). 




05 


T-STATE 


PICTURE X(02). 




05 


T-AGE 


PICTURE X(02). 




05 


T-START-DATE 


PICTURE X(06). 




05 


TRANSACTION-CODE. 








10 TRANS-TYPE 


PICTURE X(01). 






10 TRANS-ACTION 


PICTURE X(01). 


PROCEDURE DIVISION. 




BEGIN-PROCESSING. 






PERFORM FILE-OPENl. 






IF 


SK = "00" 






PERFORM PROCESS-SECTION UNTIL EOF = 1 . | 




PERFORM CLOSE-UP. 






DISPLAY " CLOSE UP PROC COMPLETE" UPON PRINTER. | 




STOP RUN. 




PROCESS 


-SECTION. 






READ TRANSACTION-FILE 


INTO TRANSACTION-RECORD 




AT 


END MOVE 1 TO EOF 






DISPLAY "TRANSACTION 


FILE PROCESSING COMPLETE" UPON PRINTER. 




IF 


EOF NOT = 1 








DISPLAY " " TRANSACTION-RECORD UPON PRINTER 






PERFORM CONTROL-SECTION. 



W Pi 
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CONTROL-SECTION. 

IF TRANS-ACTION NOT = "2" 

PERFORM READ-SECTION. 
IF TRANS-ACTION = 1 

PERFORM DELETE-PROC 
ELSE 

IF TRANS-ACTION = 2 

PERFORM ADD-PROC 
ELSE 

PERFORM UPDATE-PROC. 
READ-SECTION. 

IF TRANS-ACTION = "P" 

PERFORM READ-PRIMARY 
ELSE 

PERFORM READ-SECONDARY. 

READ-PRIMARY. 

DISPLAY " DURING PRIMARY READ" UPON PRINTER. 
DISPLAY " KEY= " T-NUMBER UPON PRINTER. 
MOVE T-NUMBER TO EMPLOYEE-NUMBER. 
READ EMPLOYEE-MASTER INTO EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID PRIMARY KEY" T-NUMBER 
UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "PRIMARY READ FAILED " T-NUMBER " " SK UPON 
PRINTER. 

READ-SECONDARY. 

DISPLAY " DURING SECONDARY READ" UPON PRINTER. 
DISPLAY " KEY= " T-LAST-NAME UPON PRINTER, 
MOVE T-LAST-NAME TO E-LAST-NAME. 
READ EMP-NAME-FILE INTO EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID SECONDARY KEY" 
T-LAST-NAME UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "SECONDARY READ FAILED" T-LAST-NAME " " SK 
UPON PRINTER. 

UPDATE-PROC. 

IF T-LAST-NAME NOT = SPACES 

MOVE T-LAST-NAME TO LAST-NAME. 
IF T-FIRST-NAME NOT = SPACES 
IF T-STREET-ADDRESS NOT = SPACES 

MOVE T-STREET-ADDRESS TO STREET-ADDRESS. 



o 



c 
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IF T-CITY NOT = SPACES 

MOVE T-CITY TO CITY. 
IF T-STATE NOT = SPACES 

MOVE T-STATE TO STATE. 
IF T-AGE NOT = SPACES 

MOVE T-AGE TO AGE. 
IF T-START-DATE NOT = SPACES 

MOVE T-START-DATE TO START-DATE. 
IF TRANS-TYPE = "P" 

PERFORM PRIMARY-REWRITE 
ELSE 

PERFORM SECONDARY-REWRITE. 

PRIMARY-REWRITE. 

DISPLAY " BEGIN PRIMARY REWRITE KEY = " T-NUMBER 

UPON PRINTER. 
MOVE T-NUMBER TO EMPLOYEE-NUMBER. 
REWRITE MASTER-RECORD FROM EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID PRIMARY KEY" 
T-NUMBER UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "PRIMARY WRITE FAILED" T-NUMBER " " SK 
UPON PRINTER. 
DISPLAY " PRIMARY REWRITE COMPLETE" UPON PRINTER. 

SECONDARY-REWRITE. 

DISPLAY " BEGIN SECONDARY REWRITE KEY = " T-LAST-NAME 

UPON PRINTER. 
MOVE T-LAST-NAME TO E-LAST-NAME. 
REWRITE EMP-NAME-RECORD FROM EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID SECONDARY KEY" 
" " T-LAST-NAME UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "SECONDARY WRITE FAILED" T-LAST-NAME " " 
SK UPON PRINTER. 
DISPLAY " SECONDARY REWRITE COMPLETE" UPON PRINTER. 

DELETE-PROC. 

IF TRANS-TYPE = "P" 

PERFORM PRIMARY-DELETE 
ELSE 

PERFORM SECONDARY-DELETE. 



^kyil' 
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PRIMARY-DELETE. 

MOVE TRANS-ACTION-RECORD TO MASTER-RECORD. 
DISPLAY " PRIMARY DELETE STARTED" UPON PRINTER. 
DELETE EMPLOYEE-MASTER RECORD 

INVALID KEY DISPLAY "INVALID PRIMARY KEY" 
T-NUMBER UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "PRIME KEY FOR DELETE NOT FOUND" 
UPON PRINTER. 
DISPLAY " PRIMARY DELETE FINISHED" UPON PRINTER. 

SECONDARY-DELETE. 

MOVE TRANS-ACTION-RECORD TO EMP-NAME-RECORD. 
DISPLAY " SECONDARY DELETE STARTED" UPON PRINTER. 
DELETE EMP-NAME-FILE RECORD 

INVALID KEY DISPLAY "INVALID SECONDARY KEY" 
T-LAST-NAME UPON PRINTER. 
IF SK NOT = "00" DISPLAY 

"SECONDARY KEY FOR DELETE NOT FOUND" UPON PRINTER 
DISPLAY TRANSACTION-RECORD UPON PRINTER. 
DISPLAY " SECONDARY DELETE FINISHED" UPON PRINTER. 

ADD-PROC. 

MOVE TRANSACTION-RECORD TO EMPLOYEE-RECORD 
IF TRANS-TYPE = "P" 

PERFORM PRIMARY-ADD 
ELSE 

PERFORM SECONDARY-ADD. 

PRIMARY-ADD. 

WRITE MASTER-RECORD FROM EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID PRIMARY KEY" 
T-NUMBER UPON PRINTER. 
IF SK NOT = "00" DISPLAY 

"INSERT FAILED FOR PRIME FILE" UPON PRINTER 
DISPLAY TRANSACTION-RECORD UPON PRINTER. 

SECONDARY-ADD. 

WRITE EMP-NAME-RECORD FROM EMPLOYEE-RECORD 

INVALID KEY DISPLAY "INVALID SECONDARY KEY" 
T-LAST-NAME UPON PRINTER. 
IF SK NOT = "00" 

DISPLAY "INSERT FAILED FOR SECONDARY FILE" 
UPON PRINTER. 
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FILE-OPENl. 

OPEN I-O EMPLOYEE-MASTER. 
IF SK NOT = "00" 

DISPLAY "OPEN FAILED FOR EMPMAST" SK UPON PRINTER 
ELSE 

OPEN 1-0 EMP-NAME-FILE 
IF SK NOT = "00" 

DISPLAY "OPEN FAILED FOR EMPNAME" SK UPON PRINTER 
ELSE 

OPEN INPUT TRANSACTION-FILE 
IF SK NOT = "00" 

DISPLAY "OPEN FAILED FOR TRANSACTION-FILE" SK 
UPON PRINTER. 
DISPLAY " FILE OPEN COMPLETE" UPON PRINTER. 

CLOSE-UP. 

DISPLAY " BEGIN CLOSE UP PROC " UPON PRINTER. 
CLOSE TRANSACTION-FILE. 
CLOSE EMP-NAME-FILE. 
IF SK NOT = "00" 

DISPLAY "CLOSE FAILED FOR EMPNAME, RC= " SK 

UPON PRINTER. 
ELSE 

DISPLAY " EMP-NAME-FILE CLOSED " UPON PRINTER. 
CLOSE EMPLOYEE-MASTER. 
IF SK NOT = "00" 

DISPLAY "CLOSE FAILED FOR EMPMAST, RC= " SK 

UPON PRINTER. 
ELSE 

DISPLAY " EMP-MAST-FILE CLOSED " UPON PRINTER. 
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PL/I INDEXED ACCESS METHOD CODING EXAMPLE 

This PL/I coding example inserts^ deletes* and updates records in an 
indexed file, using primary and secondary keys to retrieve the records. 
The indexed file is described below under "Input File". 



Program Description 

This program reads a record and based on a transaction code, either 
updates, deletes, or inserts records to a current Indexed Access Method 
file. The transaction code also determines whether index access is done 
using a secondary key or primary key. 



Input File. 



I. INPUT FILE 






A. 


TRANSACTION FILE, 








TRANSACTION RECORD 


FORMAT: 






EMPLOYEE NUMBER 


1-6 


(6) 




LAST NAME 


7-21 


(15) 




FIRST NAME 


22-31 


(10) 




ADDRESS 


32-56 


(25) 




CITY 


57-68 


(12) 




STATE 


69-70 


(2) 




AGE 


71-72 


(2) 




START DATE 


73-78 


(6) 




TYPE 


79 


(1) 




ACTION 


80 


(1) 


II. UPDATE FILE 






A. 


MASTER FILE. 








PRIMARY. KEY IS EMPLOYEE NUMBER I 


B. 


NAME FILE 








SECONDARY. KEY IS 


LAST NAME 


, 




EMPLOYEE RECORD FORMAT 






EMPLOYEE NUMBER 


1-6 


(6) 




LAST NAME 


7-21 


(15) 




FIRST NAME 


22-31 


(10) 




ADDRESS 


32-56 


(25) 




CITY 


57-68 


(12) 




STATE 


69-70 


(2) 




AGE 


71-72 


(2) 




START DATE 


73-78 


(6) 




FILLER 


79-80 


(2) 
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PLITEST: PROCEDURE OPTIONS(MAIN) ; 










DCL 


EMPMAST 


/x 


EMPLOYEE MASTER FILE 


x/ 




FILE RECORD 


/x 


PRIMARY 


x/ 




DIRECT 


/x 


KEY IS EMPLOYEE NUMBER 


x/ 




UPDATE 












KEYED 












ENV(FB BLKSIZE(256) 


RECSIZECSO) INDEXED 






KEYLENGTH(6) KEYLOC(l)); 






DCL 


EMPNAME 


/X 


EMPLOYEE NAME FILE 


x/ 




FILE RECORD 


/x 


SECONDARY 


x/ 




DIRECT 


/x 


KEY IS EMPLOYEE NAME 


x/ 




UPDATE 












KEYED 












ENV(FB BLKSIZE(256) 


RECSIZECSO) INDEXED 






KEYLENGTHdS) KEYL0C(7)); 






DCL 


TRANSFL 


/x 


TRANSACTION FILE 


x/ 




FILE RECORD 


/x 


INPUT 


r FILE 


x/ 




SEQUENTIAL 












INPUT 












ENV(FB BLKSIZE(240) 


RECSIZECSO) CONSECUTIVE); 




DCL 


SYSPRINT 


/x 


STANDARD OUTPUT FILE 


x/ 




FILE PRINT 












ENVCF BLKSIZE(121)) 


i 








DCL 


1 $FCBLST 

STATIC 
EXTERNAL, 


/x 


FILE 


CONTROL BLOCK LIST 


x/ 




2 $FCBCNT 


/x 


FILE 


COUNT 


x/ 




FIXED BIN(15) 












INIT(^), 












2 $FCBF1 


/x 


FILE 


#1 NAME 


x/ 




CHAR(8) 












INITCEMPMASTM, 












2 $FCBD1 


/x 


FILE 


«1 DATA SET 


x/ 




CHAR(8) 












INIT('EMPMAST'), 












2 $FCBV1 


/x 


FILE 


fl VOLUME 


x/ 




CHAR(6) 












INIT('EDXTST»), 












2 $FCBF2 


/x 


FILE 


#2 NAME 


x/ 




CHAR(8) 












INIT('EMPNAME'), 












2 $FCBD2 


/x 


FILE 


«2 DATA SET 


x/ 




CHAR(8) 












INITCEMPNAME'), 
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2 


$FCBV2 

CHAR(6) 
INITCEDXTST*), 


/}( 


FILE #2 VOLUME 


X/ 


2 


$FCBF3 

CHAR(8) 
INIT('TRANSFL'), 


/x 


FILE #3 NAME 


x/ 


2 


$FCBD3 

CHAR(8) 
INIT('TRANSFL'), 


/x 


FILE #3 DATA SET 


x/ 


2 


$FCBV3 

CHAR(6) 
INITCEDXTST'), 


/K 


FILE «3 VOLUME 


x/ 


2 


$FCBF4 

CHAR(8) 
INIT('SYSPRINT'), 


/K 


FILE t^ NAME 


x/ 


2 


$FCBD4 

CHAR(8) 
INIT(»SYSPRINT»), 


/K 


FILE #4 DEVICE NAME 


x/ 


2 


$FCBTL4 

FIXED BIN(15) 
INIT(l), 


/x 


FILE #4 TOP LINE 


x/ 


2 


$FCBBL4 

FIXED BIN(15) 
INIT(66), 


/^ 


FILE #4 BOTTOM LINE 


x/ 


2 


$FCBHL4 

FIXED BIN(15) 
INIT(OO); 


/x 


NOT USED 


x/ 


DCL 1 EMP RECORD 


/¥^ 


lAM BUFFER FORMAT 


x/ 


STATIC, 








2 


EMP NUMBER 
CHAR(6), 








2 


NAME, 

3 LAST NAME 

CHAR(15), 
3 FIRST NAME 

CHAR(IO), 








2 


STREET ADDRESS 
CHAR(25), 








2 


CITY 

CHAR(12), 








2 


STATE 

CHAR(2), 








2 


AGE 

CHARC2), 








2 


START DATE 
CHAR(6), 








2 


FILLER 










CHAR(2); 









o 



J-^^ 
W 
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DCL 


1 TRANSACTIONR 
STATIC, 
2 TEMP NUMBER 
CHAR(6), 
2 TNAME, 

3 TLAST NAME 

CHAR(15), 
3 TFIRST NAME 
CHAR(IO), 
2 TSTREET ADDRESS 

CHAR(25), 
2 TCITY 

CHAR(12), 
2 TSTATE 

CHAR(2), 
2 TAGE 

CHAR(2), 
2 TSTART DATE 
CHAR(6), 
2 TRANSACTION CODE, 




/x TRANSACTION RECORD FORMAT 


x/ 




3 TRANS TYPE 


/K 


»P' = PRIMARY 'S» = SECONDARY 


x/ 




CHAR(l), 










3 TRANS ACTION 


/X 


1 = DELETE 2 = INSERT 


x/ 




CHAR(l); 


/x 


3 = UPDATE 


x/ 


DCL 


BLANK 
STATIC 
CHAR (6) 
INIT(» M; 


/x 


FIELD OF BLANKS 


x/ 


DCL 


(lOERR, 


/x 


INPUT/OUTPUT ERROR FLAG 


x/ 




FOERR) 


/¥i 


OPEN ERROR FLAG 


K/ 




STATIC 










CHAR(l) 










INIT('F'); 








DCL 


TRUE 
STATIC 
CHAR(l) 
INITCTM, 


/K 


TRUE VALUE FOR FLAGS 


x/ 




FALSE 




/)< FALSE VALUE FOR FLAGS 


X/ 




STATIC 










CHAR(l) 










INITCF*); 








DCL 


R CODE 
STATIC 

FIXED BIN(15) 
INIT(O); 




/J< RETURN CODE 


x/ 
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/x ON CONDITION CODE 
/x END OF FILE FLAG 






DCL ONCODE 

BUILTIN; 
DCL EOF 

STATIC 
CHAR(l) 
INIT('F'); 
/XKXXXKXXXXX)(KXXXXXKKJ(XXXXXX MAIN PROGRAM xxxxxkxxxkxxxxxxxxxxxxx/ 
/x x/ 

/xxxxxxxxxxxxxxxxxxxxxxx ON CONDITION FOR EOF xxxxxxxxxxxxxxxxxxx/ 
ON ENDFILE(TRANSFL) 
BEGIN; 

PUT LIST(»xxx TRANSACTION FILE PROCESSING COMPLETE xxx»); 
EOF = TRUE; 

CLOSE /x CLOSE ALL FILES X/ 

FILE(EMPMAST), 
FILE(EMPNAME), 
FILE(TRANSFL); 
STOP TASK; 
END; 
/x x/ 

/xxxxxxxxxxxxxxxx ON CONDITIONS FOR FILE OPEN ERRORS xxxxxxxxxxxx/ 
ON UNDF(EMPMAST) FOERR = TRUE; 
ON UNDF(EMPNAME) FOERR = TRUE; 
ON UNDF(TRANSFL) FOERR = TRUE; 
/x x/ 

/xxxxxxxxxxxxxxxxxxxx ON CONDITIONS FOR I/O ERRORS xxxxxxxxxxxxxx/ 
ON KEY(EMPMAST) lOERR = TRUE; 
ON KEY(EMPNAME) lOERR = TRUE; 
/x x/ 

/xxxxxxxxxxxxxxxxxxxxxxxxxxx OPEN ALL FILES xxxxxxxxxxxxxxxxxxxxx/ 
/x x/ 

CALL OPEN; 
/xxxxxxx INITIATE PROCESSING UNTIL EOF CONDITION IS REACHED xxxxx/ 
DO WHILE (EOF -= TRUE); 
lOERR = FALSE; 
FOERR = FALSE; 

CALL PROCESS; /x INVOKE PROCESS SUBROUTINE x/ 
END; /x END DO WHILE x/ 

/xxxxxxxxxxxxxxxxxxxxx END MAIN PROGRAM xxxxxxxxxxxxxxxxxxxxxxxxx/ 
/x x/ 

OPEN: PROC; 

OPEN FILE(EMPMAST) UPDATE; 
IF FOERR = TRUE THEN 
DO; 

R_CODE = ONCODE; /x SET RETURN CODE X/ 

PUT LISTCOPEN FAILED FOR EMPMAST') SKIP; 
PUT LISTCON CODE = %R_CODE) SKIP; 
END; 
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IF FOERR = FALSE THEN 




DO; 




OPEN FILE(EMPNAME) UPDATE; 




IF FOERR = TRUE THEN 




DO; 




R CODE = ONCODE; /x SET RETURN CODE 


x/ 


PUT LISTCOPEN FAILED FOR EMPNAME') SKIP; 




PUT LISTCON CODE = ',R CODE) SKIP; 




END; 




END; 




/x 


x/ 


IF FOERR = FALSE THEN 




DO; 




OPEN FILE(TRANSFL); 




IF FOERR = TRUE THEN 




DO; 




R CODE = ONCODE; /* SET RETURN CODE 


x/ 


PUT LIST(»OPEN FAILED FOR TRANSFLM SKIP; 




PUT LISTCON CODE = ',R CODE); 




END; 




END; 




/x 


x/ 


IF FOERR = TRUE 




THEN 




STOP TASK; 




/x 


x/ 


END; /x END OPEN PROCEDURE x/ 




/)()()()()(X)()(XX^)()(^)(X)()(^)()( PROCESS PROCEDURE xx)()(KX)(xx)()()()(xk)(X)(XXXX)()(/ { 


/x 


x/ 


/x 1) READS IN A TRANSACTION RECORD 


x/ 


/x 2) IF ACTION = 1 DELETES RECORD WITH CORRESPONDING KEY. 


x/ 


/X =2 INSERTS RECORD ONTO lAM FILE. 


x/ 


/x =3 READS RECORD WITH CORRESPONDING KEY, 


x/ 


/x ALLOWS UPDATE, REWRITES RECORD. 


x/ 


/x 3) IF TYPE = 'P' ALL INDEXING IS DONE WITH A PRIMARY KEY 


x/ 


/x = »S' ALL INDEXING IS DONE WITH A SECONDARY KEYx/ | 


/x ^) ALL IDENTIFIERS, FILES AND RECORDS USED ARE GLOBAL 


x/ 


/x 


x/ 


/XXXXXXXXXK)(XX)(XXXXX)()CXXX)(X)(XXXXXXXXXXX)<)(XXXXXXKXXXKXXXXXXXXXXXX)(/ 1 


PROCESS: PROCEDURE; 




READ FILE(TRANSFL) INTO (TRANSACTIONR) ; 




IF lOERR = TRUE THEN 




DO; 




R CODE = ONCODE; 




PUT LISTCREAD HAS FAILED FOR TRANSFLM SKIP; 




PUT LISTCON CODE = ',R CODE) SKIP; 




END; 
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IF TRANS.ACTION = U» & lOERR = FALSE THEN 

CALL DELETE; /x BEGIN DELETE 

IF TRANS_ACTION = '3' & lOERR = FALSE THEN 
CALL UPDATE; 

IF TRANS^ACTION = '2' S lOERR = FALSE THEN 
CALL INSERT; 

END; /x END PROCEDURE PROCESS x/ 

DELETE: PROC; 

IF TRANS_TYPE = *P' 
THEN 

DELETE FILE(EMPMAST) KEY(TEMP_NUMBER) ; 
ELSE 

DELETE FILE(EMPNAME) KEYCTLAST.NAME) ; 
END; /x END DELETE ^/ 
/x 
UPDATE: PROC; 

IF TRANS_TYPE = »P' 
THEN 

CALL PRIM_READ; 
ELSE 

CALL SEC_READ; 
IF lOERR = FALSE THEN 
DO; 

IF TLAST.NAME -= BLANK 
THEN 

LAST_NAME = TLAST_NAME; 
IF TFIRST.NAME -- BLANK 
THEN 

FIRST_NAME = TFIRST_NAME; 
IF TSTREET_ADDRESS -= BLANK 
THEN 

STREET_ADDRESS = TSTREET_ADDRESS; 
IF TCITY -= BLANK 
THEN 

CITY = TCITY; 
IF TSTATE -= BLANK 
THEN 

STATE = TSTATE; 



x/ 



X/ 



f. 
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IF TAGE -= BLANK 
THEN 

AGE = TAGE; 
IF TSTART_DATE -= BLANK 
THEN 

START_DATE = TSTART_DATE; 
CALL REWRITE; 

END; /x END UPDATE x/ 

END; 

/x x/ 

PRIM_READ: PROC; 

READ FILE(EMPMAST) INTO( EMP_RECORD) 

KEY(TEMP_NUMBER); 
IF lOERR = TRUE THEN 
DO; 

R^CODE = ONCODE; 

PUT LIST(»EMPMAST PRIMARY READ HAS FAILED*) SKIP; 
PUT LIST(»KEY = » ,TEMP_NUMBER) ; 
PUT LIST( 'ONCODE = SR.CODE); 
END; 
END; /x END PRIMARY READ x/ 

/x x/ 

SEC_READ: PROC; 

READ FILE(EMPNAME) INT0( EMP.RECORD) 

KEY(TLAST_NAME); 
IF IOERR = TRUE THEN 
DO; 

R_C0DE = ONCODE; 

PUT LISTCEMPMAST SECONDARY READ HAS FAILED*) SKIP; 
PUT LISTCKEY = » ,TLAST_NAME) ; 
PUT LISTC 'ONCODE = ',R_CODE); 
END; 
END; /x END SECONDARY READ x/ 

REWRITE^ PROC* 

IF TRANS_TYPE = 'P' /x BEGIN REWRITE x/ 

THEN 

REWRITE FILE(EMPMAST) FROM(EMP_RECORD) 
KEY(TEMP_NUMBER); 
ELSE 

REWRITE FILE(EMPNAME) FROMC EMP_RECORD) 
KEY(TLAST_NAME); 
END; 
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insert: PROC; 

IF TRANS_TYPE = 'P' 
THEN 
DO; 

WRITE FILE(EMPMAST) FROM(TRANSACTIONR) 

KEYFROri(TEriP_NUMBER); 
IF lOERR = TRUE THEN 
DO; 

R_CODE = ONCODE; 

PUT LIST(»EMPMAST SECONDARY INSERTION HAS FAILED') 

SKIP * 
PUT LISTCKEY = ' ,TEMP_NUMBER) ; 
PUT LIST( 'ONCODE = »,R_CODE); 
END; 
END; 
ELSE 
DO; 

WRITE FILE(EMPNAME) FROM( TRANSACTIONR) 

KEYFROM(TLAST_NAME); 
IF lOERR = TRUE THEN 
DO; 

R_CODE = ONCODE; 

PUT LISTCEMPMAST SECONDARY INSERTION HAS FAILED') 

SKIP * 
PUT LISTCKEY = ',TNAME); 
PUT LIST( 'ONCODE = •,R_CODE); 
END; 
END; 
END; 
END PLITEST; 
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Special Characters 






$EDXLINK map 12-5 
$IAM package 11-1 
$IAM» cancelling 1 
$IAMDIR (directory) 
$IAMNP package 11- 
OIAMNRS package 11 
$IAMRSNP package 1 
$IAMUT1 

See utility, Ind 
$IAMUT1, defining f 
$IAMUT1, setting up 
$IAMUT3, call 6-1 
$ILOG 

See error loggin 
$JOBUTIL procedure 
$JOBUTIL sample pro 
$SAMPROC 13-2 
$VERIFY utility 
default working 

requirements 1 
description 10- 
error recovery p 
example 10-3 
FCB Extension re 
FCB listing 10- 
file error messa 
free space repor 
functions 10-1 
input required t 
invoking 10-2 
invoking from a 
messages 10-11 
modifying workin 
storage requirem 
summary 10-13 



1-3 

5-2 
1 

-1 
1-1 

exed Access Method 
ile 3-4 
ifile 2-2 



g faci li ty 

B-2 
cedure B-2 



storage 

0-12 

1 

rocedure 10-12 

port 10-8 

1 

ges 10-11 

t 10-9 

o execute 10-2 

program 10-3 

g storage 10-13 
ents 10-12 



o 



accessing by different keys 3-2 

accessing file 

PROCESS request 7-^ 

aids for problem solving 12-3 

AL subcommand 9-1 

AL subcommand ($IAMUT1) 9-11 

algorithm, least-recently-used 11-3 

allocate indexed file from a 
program 6-1 

allocate/insert entries, 
directory 5-3 

allocated entry, PIXB 3-14 

application program 

$JOBUTIL procedure B-2 
link-edit control data set B-2 
loading base records from 4-5 
loading secondary file with 5-16 
preparing B-1 

assembling install verify 
program 13-2 

auto-update, secondary index 7-3 

automatic update indicator 
secondary indexes 5-3 



backing up secondary index 7-9 
backup, file 7-9 
BASEREC (calculation for 

defining) A-1 
BF command ($IAMUT1) 9-4 
BLKSIZE (calculation for 

defining) A-1 
block I/O, record level 11-9 
block locks 7-2 
block mode use 11-8 
block reads, high speed 11-10 
block, read 7-8 
blocked sequential 9-23 
blocks 

calculations for defining A-1 

clusters 3-13 

clusters, calculating 3-15 

data 3-9 

data block format example 3-10 

data block, calculating 3-12 

data paging 11-3 

data, calculating initial 
number 3-16 

free 3-10 

highei — level index, 
calculating 3-19 

index 3-13 

index block, calculating 3-13 

last cluster 3-16 

locked during sequential 
reading 7-6 

primary index (PIXB) 

primary-level index 

primary-level index, 
calculating 3-16 

releasing locked 7-2 

reserve 3-15 

second-level index 

second-level index, 
calculating 3-18 
buffers 

central buffer, paging 11-3 

increasing size 11-7 

tailoring 9-4 



3-13 
3-14 



3-17 



cache 11-3 
calculati ng 

BASEREC A-1 

BLKSIZE A-1 

clusters 3-15 

data blocks 3-12 

defining data set A-1 

delete threshold A-1 

DELTHR A-1 

FPOOL A-1 

FREEBLK A-1 

FREEREC A-1 

highe? — level index blocks 3-19 

index blocks 3-13 

initial number, data blocks 3-16 

intial size, free pool 3-20 



Index X-1 



KEYSIZE A-1 

primary-level index blocks 3-16 

RSVBLK A-1 

RSVIX A-1 

second-level index blocks 3-18 
CALL instructions 8-3 
cancelling $IAM 11-3 
chaining* sequential 3-11 
clustered record inserts 3-3 
clusters 

calculating 3-15 

last 3-16 

record inserts* clustered 3-3 
COBOL coding example C-7 
COBOL programs, loading 4-1, 4-5 
codes 

-1 (successful) 8-4 

error (positive) 8-4 

negative 8-4 

positive 8-4 

requests 8-4 

return code summary. Indexed Access 
Method 8-42 

return, obtaining 12-2 

successful 8-4 

successful (-1) 8-4 

system function return 12-1 

task code word 8-4 

warning (negative) 8-4 
coding Indexed Access Method 

Requests 8-3 
components. Indexed Access 

Method 1-3, 11-2 
concurrent execution 7-2 
conditional requests 7-2 
connecting file 7-1 
contention for resource, 

avoiding 11-7 
control 

returning 7-2 
control blocks 12-5 



data 

block, calculating 3-12 

integrity 7-2 

protection 7-9 

records 2-1 
data blocks 

calculating 3-12 

format example 3-10 
data page identification 12-8 
data page location 12-9 
data paging 

adjusting size, paging area 11-3 

and sequential access 11-3 

bytes per page 11-3 

deactivate with NP 9-25 

define partitions (PP) 9-27 

description 11-3 

get statistics (PS) 9-28 

hit ratio 11-4 

identification 12-8 

least-recently-used algorithm 11-3 

location 12-9 

other performance 
considerations 11-6 

overlaying 11-3 

plot of paging area sizes 11-5 

problem solution 12-8 



read/write ratio 11-4 

select with PG 9-26 

set page area size 11-5 

set paging area size 9-27 

storage size 11-4 

using 11-5 
data record primary key 3-2 
data sets 

calculations for defining A-1 

indexed 1-1 

link-edit control B-2 

shut-down condition 7-9, 12-10 

sort, input 5-16 

sort, loading secondary index 5-16 

sort, output 5-16 

sort, work 5-16 

system error log 12-4 
data-set-shut-down condition 7-9» 

12-10 
DE subcommand 9-1 
DE subcommand ($IAMUT1) 9-12 
deadlocks 12-10 
defining 

secondary index, and loading 5-8 
defining indexed file 9-6 
DELETE record Request 8-5 
delete threshold 3-20 
delete threshold (calculating) A-1 
deleting directory entry 9-12 
deleting file 7-11 
deleting records 7-7 
DELTHR (calculation for 

defining) A-1 
DELTHR parameter 3-20 
DF command ($IAMUT1) 9-6 
DI command ($IAMUT1) 9-9 
direct reading 7-4 
direct updating 7-5 
di rectory 

$IAMDIR (directory name) 5-2 

AL subcommand 9-1 

allocate/insert entries 5-3 

allocate, with AL 9-11 

automatic update indicator 5-3 

DE subcommand 9-1 

delete, with AL 9-12 

description 5-2 

EN subcommand 9-1 

end function with EN 9-13 

f i le name 5-2 

IE subcommand 9-1 

independent processing 
indicator 5-2 

insert secondary index entry 9-14 

invalid indicator 5-3 

invoke secondary index 
functions 9-10 

LE subcommand 9-1 

list entries with LE 9-15 

subcommands 9-1 

UE subcommand 9-1 

update entry with UE 9-17 

volume name 5-2 
DISCONN Request 8-7 
disconnecting, file 7-1 
diskettes for install 13-1 
displaying indexed file 

parameters 9-9 
DR command ($IAMUT1) 9-10 
dump 

hexadecimal 7-10 

sequential 7-9 
DYN parm, adjust free pool 3-22 

option 2 
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allocating free records 3-24 
allocating free records i free 

blocks 3-26 
allocating reserved data 

blocks 3-28 
allocating reserved index 

entries 3-30 
defining a totally dynamic 

file 3-33 
dynamic file 3-22 
dynamic secondary index 5-3 



EC command ($IAriUTl) 9-19 

echo mode 9-19 

EDL CALL Function syntax 8-41 

EDL coding example C-1 

EDL program* preparing B-2 

EF command ($IAMUT1) 9-20 

EN subcommand 9-1 

EN subcommand ($IAriUTl) 9-13 

ENDSEQ Request 8-9 

entries in di rectory / 

allocate/insert 5-3 
environment. Indexed Access Method 

storage 11-2 
ERREXIT (process mode) 8-29 
ERREXIT parameter 12-3 

$EDXLINK map, use 12-5 

$IAri task, exit 12-3 

$VERIFY messages 10-11 

abnormal system termination 12-7 

data paging problems 12-8 

data-set-shut-down condition 12-10 

deadlocks 12-10 

exit 12-3 

file control block, FCB 12-5 

handling 12-1 

lACB characteristics 12-5 

information location 12-5 

log data set 12-4 

logging facility 12-4 

long-lock-time condition 12-10 

malfunctions, isolate 12-9 

messages to $SYSLOG 12-3 

recovery procedure 10-12 

run loops 12-7 

system dump, use 12-5 

task, exit 12-2 

verifying requests and files 12-9 

wait states 12-5 
error logging and reporting, 

$IAMUT3 6-6 
error logging facility 

deadlocks 12-10 

log data set 12-4 

long-lock-time condition 12-10 

malfunctions, isolate 12-9 

verifying requests and files 12-9 
error report, $ILOG 6-6 
error return code, request 8-4 
examples 

$JOBUTIL sample procedure B-2 

calculations for defining data 
set A-1 

COBOL coding C-7 



EDL coding C-1 

how to use Indexed Access 
Method 2-1 

link-edit control data set B-3 

option 2 3-23 

option 3 3-36 

PL/I coding C-14 

sample programs C-1 

verifying a file 10-3 
executi on 

concurrent 7-2 

installation verify program 13-2 
exi t 

$IAM task error 12-3 

error 12-3 

routine 12-3 

task error 12-2 
EXTRACT request 7-7, 8-11 



FCB 

See file control block 
FCB characteristics 12-5 
FCB Extension 

See file control block extension 
FCBEQU 7-7 
FCBEQU module 8-11 
file control block 

description 7-7 

extension 3-21 

extracting file information 8-11 

FCB listing, $VERIFY 10-1 

FCBEQU 7-7 

location 3-21 

report, $VERIFY 10-6 
file control block 

characteristics 12-5 
file control block extension 

See also file control block exten- 
si on 

description 7-7 

extracting file information 8-11 

FCBEQU 7-7 

report, $VERIFY 10-8 
format, secondary record 5-17 
forward pointers 3-11 
FPOOL (calculation for defining) A-1 
free block entry, PIXB 3-15 
free block entry, SIXB 3-17 
free blocks 3-10 
free pool 

adjusting with DYN 3-22 

calculating 3-20 

delete threshold 3-20 

DELTHR parameter 3-20 

description 3-20 
free records 3-10 
free space 

blocks 3-10 

records 3-10 

reserve blocks 3-10 

reserve index entries 3-10 
FREEBLK (calculation for 

defining) A-1 
FREEREC (calculation for 
defining) A-1 



Index X-3 



GET record Request 8-14 
GETB 7-8 

description 8-2 

get block request 8-17 
GETBC 

description 8-17 

get block request 8-17 
GETNB 7-8 

description 8-2 

get next block request 8-20 
GETNBC 

description 8-20 

get next block request 8-20 
GETSEQ Request 8-22 



header 3-9 

hexadecimal dump of file 7-10 
high speed block reads 11-10 
highei — level index block 

calculating 3-19 

calculations for defining A-1 

description 3-19 

index levels* performance 11-6 

structure 3-19 
hit ratio 11-4 
HIXB 

See highei — level index block 
hoM to use Indexed Access Method 2-1 



m 



lACBs 

disconnect from file 7-2 

holding lock 7-2 

multiple 7-2 
JAM link module 1-3 
lAMFR link module 1-3 
IE subcommand 9-1 
IE subcommand ($IAMUT1) 9-14 
immediate write-back option 2-4 
independent processing indicator 5-2 
index block 

calculating 3-13 

primary level 3-14 
index blocks 3-13 
Indexed Access Control Block* 

lACB 12-5 
Indexed Access Method 

components 1-3* 11-2 

features 1-1 

installing 13-1 

languages compatible with 1-3 

packages 11-1 

performance 11-3 

requests 2-7 
, storage requirements 11-1 

what it does 1-1 
indexed data sets 1-1 
indexed file 

accessing 7-4 

backup and recovery 7-9 

blocks 3-7 



calculations for defining A-1 
connecting* disconnecting 7-1 
control block (FCB) 3-21 
data paging 11-3 
define with DF 9-6 
defining and loading 2-1 
defining using existing data 

set 3-4 
defining with $IAMUT1 3-4 
defining with all parameters 3-4 
defining with minimum 

parameters 3-4 
defining, all parms 3-7 
defining* minimum parms 3-5 
defining* with existing file 

parms 3-35 
deleting 7-11 
deleting records from 7-7 
direct block reading 7-8 
disconnect lACB from 7-2 
display characteristics 9-20 
dynamic 3-22 
error messages 10-11 
extracting information 7-7 
failure to disconnect 7-2 
FCB 7-7 

FCB Extension 3-21* 7-7 
file name* directory 5-2 
free space 3-10 
independent 5-2 
inserting new records in 7-7 
inserting record* no space 

for 7-10 
journal 7-9 

levels affect performance 11-6 
load with LO 9-22 
loading secondary with application 

program 5-16 
loading* from a sequential 

file 4-4 
loading* primary 4-1 
logical structure 3-8 
maintaining 7-9 
open (PROCESS) 8-29 
open for loading (LOAD) 8-25 
pointers* verify 10-1 
preparing input for 4-3 
primary 3-1 
prior to using 7-1 
processing 2-6 
put record in 8-34 
record* no space for 

inserting 7-10 
recovery without backup 7-10 
reorganize (RO) 9-30 
reorganizing 7-10 
resetting parameters 9-29 
secondary* format 5-16 
sequential blocked 9-23 
sequential unblocked 9-23 
set parms, structure/size 9-32 
size/performance 11-6 
structure affects performance 11-6 
structure types 3-21 
structure* defining 3-4 
structured 3-21 
unload (with UN) 9-41 
verifying 7-11* 12-9 
verifying* example 10-3 
indi cator 

automatic update 5-3 
independent 5-2 
invalid 5-3 
information* extracting 7-7 
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input/output 

buffer size» increasing 11-7 

data-set-shut-down error 
condition 12-10 

echo mode 9-19 

preparing input for indexed 
file 4-3 
insert/allocate entries^ 

directory 5-3 
inserting records 7-7 
inserts 

clustered 3-3 

random 3-3 

reserving space for 3-11 
installation 

diskettes for 13-1 

Indexed Access Method 13-1 

planning for 13-1 

running verify program 13-2 
integrity* data 7-2 
invalid indicator 5-3 



base records from sequential 
file fi-5 

COBOL programs 4-1 

indexed file from sequential 
file 4-4 

load mode 4-1 

module 13-1 

open f i le for 8-25 

primary file 4-1 

process mode 4-l» 7-2 

secondary* sort data sets 5-16 

sequentially 7-2 

unloading (with UN) 9-41 
locate information 12-5 
lock-time condition 12-10 
locked record during update 7-5 
locks 

deadlocks 12-10 

long-lock-time condition 12-10 

record or block 7-2 

release 7-5 
log» system error 12-4 
logging facility* error 12-4 
long-lock-time condition 12-10 
looping 12-7 



journal file 7-9 
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key 

defining 3-2 

defining primary 3-2 

duplicate* retrieval 7-3 

ensuring uniqueness 3-2 

more than one 3-2 

primary 2-1 

random order* loading 4-5 

secondary 2-1, 5-1 
key relational parameter 

See krel 
KEYSIZE (calculation for 

defining) A-1 
krel 

record retrieving using 7-4 



maintaining indexed file 7-9 
malfunctions* isolate 12-9 
master control block* CDIMCB 12-5 
messages 

$VERIFY 10-11 

f i le error 10-11 
modules 

link 13-1 

load 13-1 

removal of storage 11-3 

source 13-1 
multitasking environment* overlay 



7-4 



negative return code 8-4 
NP command ($IAMUT1) 9-25 



languages to code Indexed Access Meth- 
od programs 1-3 

last cluster 3-16 

LE subcommand 9-1 

LE subcommand ($IAMUT1) 9-15 

least-recently-used algorithm 11-3 

link map 12-5 

link module 13-1 

link-edit application program B-2 

link-edit considerations 8-4 

LO command ($IAMUT1) 9-22 

load mode 4-1 

load module 13-1 

LOAD Request 8-25 

loadi ng 

$IAMUT1* using 4-3 
and defining secondary index 5-8 
base records from application 
program 4-5 



open file, using PROCESS 8-29 
opti ons 

examples* option 2 3-23 

examples* option 3 3-35 

selection guide 3-4 

selection guide* secondary 
indexes 5-9 

1* define secondary index 5-10 

1, define with minimum parms 3-5 

2, define secondary index 5-12 

2* define with specific parms 3-7 
3* define secondary index 5-14 
3* defining with existing 
parms 3-35 
output 

FOB Extension report 10-8 
FOB report 10-6 



Index X-5 



free space report 10-9 
overlay 

in multitasking environment 7-4 



packages 

$IAM 11-1 
$IAMNP 11-1 
$IAMNRS 11-1 
$IAMRSNP 11-1 

page identification 12-8 

page location 12-9 

paging 

See data paging 

parameter list» $IAMUT3 6-6 

parameters 

defining file with all 3-4 
defining file with minimum 3-4 
defining using existing data 

set 3-4 
display with DI command 9-9 
parm3» parm4, parmS 8-4 
reset 9-29 
set (with SE) 9-32 
values* display 9-9 

parm3* parm4» parmS 8-4 

performance 

data paging feature 11-3 
file size affects 11-6 
file structure affects 11-6 
reducing index levels 11-6 
secondary index affects 11-11 

PG command (SIAMUTl) 9-26 

PIXB 

See primary-level index block 

PL/I coding example C-14 

planning for install 13-1 

pointers* forward 3-11 

pointers* verify 10-1 

positive return code 8-4 

PP command ($IAMUT1) 9-27 

primary index blocks 3-13 

primary index files 3-1 

primary-level index block 
allocated entry 3-14 
calculating 3-16 
calculations for defining A-1 
free block entry 3-15 
index levels* performance 11-6 
reserve block entry 3-15 

priorities* task 7-1 

problem solving aids 12-3 

process mode 4-1 

process mode* loading 7-2 

PROCESS Request 8-29 

PROCESS request, access file 7-4 

processing indexed file 2-6 

program 

application, link-edit B-2 
application, preparing B-1 
loading base records from 4-5 
variables 8-4 

protecting data 7-9 

PS command ($IAMUT1) 9-28 

PUT Request 8-34 

PUTDE Request 8-36 

PUTUP Request 8~38, 8-40 



random loading* base records 4-5 

random record inserts 3-3 

RBN (relative block number) 3-21 

RE command ($IAMUT1) 9-29 

read/write ratio 11-4 

reading* direct 7-4 

reading* sequential 7-5 

record 

base* loading 4-1 

calculations for defining A-1 

clustered inserts 3-3 

concurrent modification 7-2 

delete previously read 8-36 

deleting 7-7 

direct reading 7-4 

direct updating 7-5 

free 3-10 

GETSEQ request 7-5 

insert, no space for 7-10 

inserting 3-3* 7-7 

loading from application 
program 4-5 

loading from sequential file* ran- 
dom order 4-5 

locked during update 7-5 

locks 7-2 

put in file 8-34 

random inserts 3-3 

releasing 7-2 

releasing lock 7-5 

reserving space for inserts 3-11 

retrieving 7-3 

sample layout 2-1 

secondary* format 5-17 

sequential reading 7-5 

sequential updating 7-6 

setting up with $IAMUT1 2-2 

update 8-38* 8-40 

verify sequence 10-1 
record level block I/O 11-9 
recovery 

file backup 7-9 

procedure* $VERIFY 10-12 

without backup 7-10 
recreating file 7-10 
relative block number (RBN) 3-21 
release lock on record 7-5 
releasing locked blocks 7-2 
reorganize indexed file 7-10, 9-30 
reorganizing secondary index 7~10 
reports 

FCB 10-6 

FCB Extension 10-8 

free space 10-9 
request functions* coding C-1 
requests* Indexed Access Method 2-7 

CALL instructions 8-3 

coding 8-3 

DELETE (delete record) 8-5 

DISCONN (close file) 8-7 

ENDSEQ (sequential processing) 8-9 

error return code 8-4 

EXTRACT (get file 
information) 8-11 

GET (get record) 8-14 

GETB (get block) 8-17 

GETBC (get block) 8-17 

GETNB (get next block) 8-20 

GETNBC (get next block) 8-20 
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GETSEQ (get rRCord^ 
sequential) 8-22 

link-edit considerations 8-4 

list and description 8-2 

LOAD (open file for loading) 8-25 

PROCESS (open file) 8-29 

program variables 8-4 

PUT (put record in file) 8-34 

PUTDE (delete record) 8-36 

PUTUP (update record) 8-38 

RELEASE (record) 8-40 

return codes 8-4 

successful return code 8-4 

Naming return code 8-4 
requests^ verifying 12-9 
reserve block entry* PIXB 3-15 
reserve index entry » SIXB 3-18 
resetting indexed file 

parameters 9-29 
resource contention* avoiding 11-7 
resources* locked 12-10 
retri eving 

direct* secondary index 7-3 

duplicate keys 7-3 

sequential* secondary key 7-3 
return codes 

See codes 
RO command ($IAMUT1) 9-30 
routine* exit 12-3 

RSVBLK (calculation for defining) A-1 
RSVIX (calculation for defining) A-1 
run loops 12-7 

data paging problems 12-8 



SE command ($IAMUT1) 9-32 
search argument 7-4 
second-level index blocks 

calculating 3-18 

calculations for defining A-1 

description 3-17 

free block entry 3-17 

index levels* performance 11-6 

reserve index entry 3-18 
secondary index 

allocate/insert entries* 
directory 5-3 

application programs 5-7 

auto-update 7-3 

automatic update indicator 5-3 

backing up 7-9 

define options* guide for 
selecting 5-9 

defining with existing parms 5-14 

defining with minimum parms 5-10 

defining with specific parms 5-12 

defining/loading 5-8 

description 5-1 

direct retrieval 7-3 

directory 5-2 

dynamic 5-3 

example* defining using 
$IAMUT1 5-10 

file format 5-16 

f i le name 5-2 

guide for selecting options 5-9 

independent processing 
indicator 5-2 

insert entry with IE 9-14 

invalid indicator 5-3 



invoke directory 9-10 

list entries with LE 9-15 

loading with application 
program 5-16 

option selection guide 5-9 

performance considerations 11-11 

reorganizing 7-10 

secondary key 5-1 

secondary keys 7-3 

secondary record format 5-17 

setting up 5-8 

sort data sets for loading 5-16 

static 5-3 

structure 5-8 

update entries with UE 9-17 

verify contents ($VERIFY) 10-1 

volume name 5-2 
secondary keys 

accessing file by 7-3 

sequential retrieval 7-3 

using 7-3 
sequential 

access and data paging 11-3 

chaining 3-11 

dump 7-9 

ENDSEQ Request 8-9 

file* loading base records 
from 4-5 

file* loading from 4-4 

GETSEQ Request 8-22 

load mode 4-1, 7-2 

reading 7-5 

retrieval 7-3 

updating 7-6 
sequential processing 11-7 
SIXB 

See second-level index blocks 
soft exception 12-2 
sort input data set 5-16 
sort output data set 5-16 
sort work data set 5-16 
Sort/Merge, sort data sets 5-16 
source module 13-1 
space 

calculations for defining A-1 

free 3-10 

reserving 3-11 

reserving for inserts 3-11 
space requirements 13-1 

load 

FCBEQU 13-1 
lAM 13-1 
lAMEQU 13-1 
lAMFR 13-1 
static secondary index 5-3 
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